Salesforce MCP

Configure Salesforce Hosted MCP servers in IntelliAsk with an External Client App and per-user OAuth.

Salesforce Hosted MCP servers let IntelliAsk users connect to Salesforce through per-user OAuth. Each tool call runs with the authenticated Salesforce user's permissions, including field-level security, object permissions, and sharing rules.

Use an External Client App

Salesforce Hosted MCP servers require an External Client App. Classic Salesforce Connected Apps are not supported for Hosted MCP authentication.

What You Will Configure

This guide starts with the read-only SObject server because it is the safest first connection. After that works, you can switch to a broader Salesforce server.

Server	Access level	Production URL	Sandbox or scratch URL
SObject Reads	Read, query, search, relationships	`https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads`	`https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads`
SObject Mutations	Read, create, update, no delete	`https://api.salesforce.com/platform/mcp/v1/platform/sobject-mutations`	`https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-mutations`
SObject Deletes	Delete-focused workflows	`https://api.salesforce.com/platform/mcp/v1/platform/sobject-deletes`	`https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-deletes`
SObject All	Full create, read, update, delete	`https://api.salesforce.com/platform/mcp/v1/platform/sobject-all`	`https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all`

OAuth callback path

IntelliAsk's MCP OAuth callback path is BASE_URL/api/mcp/SERVER_NAME/oauth/callback. SERVER_NAME is the key under mcpServers in intelliask.yaml. The examples below use salesforce, so the local callback is http://localhost:3080/api/mcp/salesforce/oauth/callback.

Prerequisites

A Salesforce org that supports Hosted MCP servers and API access.
System Administrator permissions, or equivalent permissions to create External Client Apps and enable MCP servers.
A running IntelliAsk instance with intelliask.yaml mounted or otherwise loaded.
The public base URL users use to open IntelliAsk, for example http://localhost:3080 for local development or https://chat.example.com for production.

If you do not have a Salesforce org yet, create a free Developer Edition org from developer.salesforce.com/signup, verify the account by email, then log in at login.salesforce.com. If the Salesforce Setup menus in this guide are not visible in the org, use a supported production, sandbox, or trial org with Hosted MCP servers enabled.

Setup

Activate the Salesforce MCP server

In Salesforce, open Setup.

In Quick Find, search for MCP Servers.
Open MCP Servers under API Catalog.
Enable the server you want to use. For first setup, enable platform/sobject-reads.
Wait up to 2 minutes for the server to become active.

If you plan to use the full-access example, enable platform/sobject-all instead.

Create an External Client App

In Salesforce Setup:

In Quick Find, search for External Client App Manager.
Click New External Client App.
Fill out the basic app information. Use a clear name, such as IntelliAsk Salesforce MCP.
Expand API (Enable OAuth Settings) and enable OAuth.
Add the IntelliAsk callback URL.

For local development:

http://localhost:3080/api/mcp/salesforce/oauth/callback

For production, replace the base URL with your public IntelliAsk URL:

https://chat.example.com/api/mcp/salesforce/oauth/callback

Configure OAuth scopes and security

In the External Client App OAuth settings, add these scopes:

mcp_api
refresh_token

Do not use the standard Salesforce api scope for Hosted MCP servers. The MCP server expects the mcp_api scope.

In the External Client App security settings:

Select Issue JSON Web Token (JWT)-based access tokens for named users.
Select Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows.
Leave Require Secret for Web Server Flow disabled for the basic setup in this guide.
Leave Require Secret for Refresh Token Flow disabled for the basic setup in this guide.

Click Create, then open the app settings and copy the Consumer Key. Salesforce says a new External Client App can take up to 30 minutes to become available.

Optional client secret

IntelliAsk can store a client secret server-side. If your Salesforce admin enables Require Secret for Web Server Flow, also generate a client secret and include the optional client_secret fields shown later in this guide.

Add the Salesforce client ID to `.env`

Add the External Client App consumer key to your IntelliAsk .env file:

SALESFORCE_MCP_CLIENT_ID=your-salesforce-consumer-key

If you enabled Require Secret for Web Server Flow, also add:

SALESFORCE_MCP_CLIENT_SECRET=your-salesforce-client-secret

Add Salesforce MCP to `intelliask.yaml`

This example configures the read-only SObject server for a production or Developer Edition org:

mcpServers:
  salesforce:
    type: streamable-http
    url: 'https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads'
    timeout: 90000
    initTimeout: 150000
    requiresOAuth: true
    startup: false
    oauth:
      authorization_url: 'https://login.salesforce.com/services/oauth2/authorize'
      token_url: 'https://login.salesforce.com/services/oauth2/token'
      client_id: '${SALESFORCE_MCP_CLIENT_ID}'
      scope: 'mcp_api refresh_token'
      redirect_uri: 'http://localhost:3080/api/mcp/salesforce/oauth/callback'

For a sandbox or scratch org, use the sandbox MCP URL and Salesforce sandbox OAuth endpoints:

mcpServers:
  salesforce:
    type: streamable-http
    url: 'https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads'
    timeout: 90000
    initTimeout: 150000
    requiresOAuth: true
    startup: false
    oauth:
      authorization_url: 'https://test.salesforce.com/services/oauth2/authorize'
      token_url: 'https://test.salesforce.com/services/oauth2/token'
      client_id: '${SALESFORCE_MCP_CLIENT_ID}'
      scope: 'mcp_api refresh_token'
      redirect_uri: 'http://localhost:3080/api/mcp/salesforce/oauth/callback'

If your External Client App requires a client secret, add these fields inside oauth:

oauth:
  client_secret: '${SALESFORCE_MCP_CLIENT_SECRET}'
  token_exchange_method: default_post
  token_endpoint_auth_methods_supported: ['client_secret_post']

If IntelliAsk is deployed at a public URL, update redirect_uri to match the exact callback URL registered in Salesforce.

Strict MCP domain allowlists

If your intelliask.yaml also configures mcpSettings.allowedDomains, add api.salesforce.com. If you use Salesforce sandbox OAuth endpoints and your policy also applies to OAuth hosts, allow test.salesforce.com or your sandbox My Domain host as well.

Switch to full Salesforce access, if needed

After the read-only server works, you can switch to another activated Salesforce server by changing the url.

For full SObject access in a production or Developer Edition org:

url: 'https://api.salesforce.com/platform/mcp/v1/platform/sobject-all'

For full SObject access in a sandbox or scratch org:

url: 'https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all'

Only expose mutation or delete-capable servers to users who should be allowed to create, update, or delete Salesforce records through an assistant.

Restart IntelliAsk

Restart IntelliAsk so it reloads .env and intelliask.yaml.

Deployment	Command
Docker	`docker compose up -d`
Local	Stop the server, then start it again

To confirm the server loaded in Docker, check the API logs:

docker logs IntelliAsk --tail 200 | grep MCP

Connect Salesforce in IntelliAsk

Open IntelliAsk, then open MCP Settings or the MCP Servers dropdown in the chat input.

Click Connect for the Salesforce server.
Complete the Salesforce OAuth flow.
Review the requested mcp_api and refresh_token scopes.
Return to IntelliAsk after the OAuth success page closes.

After OAuth succeeds and the MCP connection initializes, Salesforce tools become available in chat and in the Agent Builder.

Testing

Try prompts that match the server you enabled:

Server	Prompt
Any SObject server	"Who am I in Salesforce?"
SObject Reads	"Show me my five most recently viewed accounts."
SObject Reads	"Find open cases related to Acme Corp and summarize them."
SObject Mutations	"Create a follow-up task for this account. Ask me before saving anything."
SObject All	"Update this opportunity stage to Closed Won after confirming the exact record."

For a lower-level sanity check, test the same Salesforce server with Postman or MCP Inspector. If that works but IntelliAsk does not, compare the IntelliAsk callback URL, OAuth scopes, and server URL against the working client.

Troubleshooting

Symptom	What to check
Salesforce says `redirect_uri_mismatch`	The External Client App callback URL must exactly match the `redirect_uri` in `intelliask.yaml`, including protocol, hostname, port, server name, and path.
Salesforce Login History says `Invalid Code Verifier`	PKCE state did not match the callback. Avoid starting multiple OAuth flows at once. In multi-replica deployments, make sure IntelliAsk uses shared OAuth flow storage, such as Redis, so authorize and callback requests can land on different replicas safely.
Salesforce returns `JWT Token is required`	The server is being called without a Salesforce MCP access token. Complete OAuth from IntelliAsk, confirm `requiresOAuth: true`, and confirm the user authorized the External Client App.
Salesforce returns `Invalid token`	Confirm the External Client App uses `mcp_api`, issues JWT-based access tokens, and has PKCE enabled. Also confirm the MCP URL and OAuth endpoints point to the same org type, production versus sandbox.
Salesforce returns `Server definition not found for: sobject-all`	The server is not activated, is still propagating, or the URL uses the wrong production versus sandbox path. Enable the server in Salesforce Setup and wait up to 2 minutes.
Token refresh fails with a scope-related error	Use `mcp_api refresh_token` as the configured scope. Do not substitute the regular Salesforce `api` scope for Hosted MCP.
IntelliAsk shows Salesforce but no tools	Connect the server from the IntelliAsk UI. OAuth-enabled remote servers expose tools after the user has authenticated and the server has initialized.
MCP requests are blocked by IntelliAsk domain policy	If `mcpSettings.allowedDomains` is configured, allow `api.salesforce.com` and any Salesforce OAuth host your deployment uses.

Security Notes

Start with platform/sobject-reads unless users truly need write or delete access.
Salesforce enforces the authenticated user's permissions, but the assistant can still propose broad actions. Review write and delete operations carefully.
Use Salesforce permission sets and External Client App policies to restrict who can authorize the MCP client.
Treat Salesforce records as untrusted input. Records can contain indirect prompt injection attempts that try to influence the assistant.
For production deployments with multiple IntelliAsk API replicas, use shared storage for OAuth flow state so PKCE callbacks are durable across replicas.

MCP

Learn how MCP servers work in IntelliAsk.

→

MCP Servers Object Structure

Review every available mcpServers configuration field.

→

Salesforce Hosted MCP servers

Read Salesforce's official Hosted MCP setup documentation.

→