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
- In Salesforce, go to Setup → External Client App Manager → New External Client App. See Salesforce’s Create an External Client App for reference.
-
Under Basic Information, enter a recognizable Name (for example
TrueFoundry MCP Gateway), a Contact Email, and a description. - Expand API (Enable OAuth Settings) and check Enable OAuth.
-
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 thehttps://scheme. -
Move these scopes from Available OAuth Scopes to Selected OAuth Scopes. All three are required:
mcp_apireplaces the oldersfap_apiscope 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)
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.
- Refresh Token Policy - Expire refresh token if not used for specific time, with Refresh Token Validity Period
30and UnitDay(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.
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.
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:- Standard servers
- Headless 360 (Beta)
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.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, registersobject-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.