Skip to main content
Salesforce is a CRM platform for accounts, contacts, opportunities, cases, and custom objects. Salesforce exposes Hosted MCP servers from inside your org that let agents read and change CRM records. Every call runs as the authenticated user and honors that user’s CRUD permissions, field-level security, sharing rules, and permission sets. Register them on the TrueFoundry MCP Gateway and your agents reach Salesforce through one governed endpoint. You create an External Client App in your own org and add its Client ID and Client Secret to the TrueFoundry server config, so Salesforce-side identity, scopes, and governance stay inside your org while the Gateway handles inbound auth, access control, observability, and guardrails. Salesforce offers two families of Hosted MCP servers, and this guide covers both:
Salesforce Hosted MCP requires an External Client App. Classic Connected Apps are not supported for Hosted MCP authentication.

Using Salesforce through the MCP Gateway

When you use the Salesforce MCP server through the AI Gateway, TrueFoundry provides:
  • Authentication - Clients authenticate inbound to the AI Gateway with a Personal Access Token, Virtual Account, or IDE OAuth flow. For outbound access, the AI Gateway runs the OAuth2 Authorization Code flow against your External Client App, so each user authorizes their own Salesforce account.
  • Tool-level access control - Enable or disable individual Salesforce tools from the server detail page. Disabling write and delete tools at the Gateway keeps an agent read-only.
  • Access control - Collaborators and role-based policies define who can use the server and which tools they can invoke.
  • Observability - Tool calls are traced with caller identity, tool name, inputs, and latency. Monitor server- and tool-level usage in MCP Metrics and export traces to your observability stack via OpenTelemetry.
  • Guardrails - Apply pre-tool and post-tool guardrails on MCP tool calls - useful here because a single query tool call can return customer records.

Prerequisites

  • A TrueFoundry account with permission to add MCP servers, and your TrueFoundry control plane base URL.
  • A Salesforce org with Hosted MCP support and API access enabled (Developer, Enterprise, or Professional Edition with API access).
  • System Administrator (or equivalent) permission in Salesforce, to create External Client Apps and activate MCP servers.
  • Whether you’re connecting to a Production org or a Sandbox / Scratch org - the MCP server URL differs.

Adding Salesforce MCP server to TrueFoundry

1

Create an External Client App

  1. In Salesforce, go to Setup → External Client App Manager → New External Client App. See Salesforce’s Create an External Client App for reference.
  2. Under Basic Information, enter a recognizable Name (for example TrueFoundry MCP Gateway), a Contact Email, and a description.
  3. Expand API (Enable OAuth Settings) and check Enable OAuth.
  4. Set the Callback URL to TrueFoundry’s OAuth callback:
    Replace <tfy-control-plane-base-url> with your TrueFoundry control plane URL. It must match exactly, including the https:// scheme.
  5. Move these scopes from Available OAuth Scopes to Selected OAuth Scopes. All three are required: mcp_api replaces the older sfap_api scope for Hosted MCP. Leave Introspect all Tokens and Configure ID token unchanged.
2

Configure flows and security

Under Flow Enablement, enable only Enable Authorization Code and Credentials Flow. Leave Client Credentials, Device, JWT Bearer, Token Exchange, and Require user credentials in the POST body off.Under Security, enable:
  • Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows (required)
  • Enable Refresh Token Rotation (required)
  • Issue JSON Web Token (JWT)-based access tokens for named users
  • Limit Idle Refresh Token Time-to-Live (TTL) to 30 Days (required)
Leave the remaining options off. Require secret for Web Server Flow stays off for a public client using PKCE. Turn it on only if you want a confidential client, in which case TrueFoundry also needs the Consumer Secret.Then select Create to save the app.
3

Set the OAuth policies

Open the saved app, edit the OAuth Policies section, and set:Plugin Policies
  • Permitted Users - All users can self-authorize, so each user completes their own consent and every call runs under that user’s Salesforce permissions. Choose Admin approved users are pre-authorized instead if you want to gate access through profiles or permission sets.
  • Leave OAuth Start URL, Custom Scopes, and Apex Plugin Class empty.
App Authorization
  • Refresh Token Policy - Expire refresh token if not used for specific time, with Refresh Token Validity Period 30 and Unit Day(s), matching the 30-day idle TTL set in Security.
  • IP Relaxation - Relax IP restrictions, since calls come from the TrueFoundry Gateway rather than a fixed user IP. If your security policy requires IP enforcement, keep the restrictions and allowlist TrueFoundry’s egress IPs instead.
  • Named User JWT-Based Access Token Settings - Use the user’s default session timeout.
  • Leave Enable Single Logout and High Assurance Session Required off.
Save the policies.
4

Copy the Consumer Key

In the app, open Settings → OAuth Settings → Consumer Key and Secret and copy the Consumer Key - this is the Client ID for TrueFoundry. Copy the Consumer Secret only if you enabled Require secret for Web Server Flow.
A new External Client App can take up to about 30 minutes to become fully active. OAuth errors during this window usually resolve on their own.
If you use a Consumer Secret, store it in the TrueFoundry secrets store and reference it by FQN in the server config rather than pasting it inline.
5

Activate the MCP server

In Setup, search the Quick Find box for MCP Servers, find the server you want, and click Activate. Activation can take up to two minutes. See Salesforce’s Activate MCP Servers.The server URL follows this pattern, where <server-name> is the server you activated:
Activate the server that matches the access level you need. Start with read-only access and widen it later:For example, read-only access on a production org uses https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads.
6

Register the MCP server in TrueFoundry

In MCP Servers, click Add new MCP Server, select Connect any Remote MCP Server, and configure:Add Collaborators - the users and teams that can use or manage this server - and assign each an MCP Server Manager or MCP Server User role. Then save.Add one TrueFoundry MCP server per Salesforce server you want to expose - for example, one for sobject-reads and another for headless-360. They can all share the same External Client App.
7

Connect and verify

Open the server’s Tools tab and click Connect Now. TrueFoundry runs the authorization-code flow: you log in to Salesforce, review the requested permissions, click Allow, and land back on the server detail page. Each user connects once with their own identity.After connecting, the Tools tab lists the server’s tools.

Connecting to an MCP Client

Open the How To Use tab on the Salesforce server detail page for your tenant-specific Gateway URL and ready-to-paste client snippets - don’t build the endpoint manually. The tab includes snippets for Claude Code, VS Code, Claude Web, Claude Desktop, Cursor, Windsurf, Codex, and the Python and TypeScript MCP SDKs. For step-by-step setup in each client, see Connect MCP from your IDE.
Require approval in your client before any tool that changes org configuration or creates, updates, or deletes data - especially for administrators and developers with broad Salesforce permissions. See MCP Tool Approval.

Tool Metrics

The Tool Metrics tab tracks invocation count, latency, and error rates per tool. See MCP Metrics for server- and tool-level dashboards across your Gateway.

Disabling Individual Tools

On the Tools tab, toggle off any Salesforce tools your agents don’t need. Disabled tools are hidden from MCP clients and cannot be invoked. See MCP Tool Management for denylist and allowlist modes. For a read-only agent, register sobject-reads instead of sobject-all. With Headless 360, disable Dispatch and keep Dispatch (Read-Only) to block writes at the Gateway, independent of the user’s Salesforce permissions.