Hosted MCP Servers Setup and Authentication

Overview#

Salesforce Hosted Model Context Protocol (MCP) Servers expose your org’s data, metadata, automation, and analytics to external AI clients—including Claude, Cursor, ChatGPT, Postman, and Agentforce Vibes—through a single governed protocol. Instead of building and maintaining custom REST API middleware for every AI assistant in your stack, you configure authentication once in Salesforce and connect any MCP-compatible host over HTTPS.

Every Hosted MCP Server operates strictly inside the Salesforce security perimeter using per-user OAuth 2.0 authentication with Proof Key for Code Exchange (PKCE). When an AI agent invokes a tool, the server executes deterministic platform calls as the authenticated human user, enforcing that user’s object permissions (CRUD), field-level security (FLS), and sharing rules automatically.

Prerequisites#

You need administrator access, an API-enabled Salesforce edition, and an MCP-compatible client before configuring a connection:

• System Administrator permissions (or equivalent permissions to manage External Client Apps and API Catalog settings in Setup).
• API access enabled on the target org (Enterprise, Unlimited, Performance, Developer Edition, or Professional Edition with API add-on).
• Flex Credits entitlement enabled on your contract for production usage.
• Target MCP client details, specifically the OAuth callback URL required by your client (Postman, Claude, Cursor, or ChatGPT).

Enable Hosted MCP Servers in Setup#

Hosted MCP Servers are disabled by default in every org and must be explicitly activated by an administrator before any client can connect. Even if a user completes OAuth authentication with valid credentials, connection requests fail until the target server is toggled on.

1. In Salesforce Setup, enter MCP Servers in the Quick Find box and select MCP Servers under API Catalog.
2. Review the catalog of available standard servers (such as platform/sobject-reads or platform/sobject-all) and custom servers.
3. Toggle on only the specific servers your team requires. Wait up to 2 minutes for newly activated servers to become operational.

Configure an External Client App for OAuth 2.0 PKCE#

Salesforce Hosted MCP Servers require an External Client App (ECA) for OAuth registration. Legacy Connected Apps are not supported and will fail authentication.

Step-by-Step ECA Configuration#

1. In Setup, enter external client in the Quick Find box and select External Client App Manager.
2. Click New External Client App and complete the Basic Information fields (App Name, API Name, Contact Email).
3. Expand API (Enable OAuth Settings) and select Enable OAuth.
4. In Callback URL, enter the exact redirect URI for each MCP client you plan to use (you can register multiple callback URLs on separate lines):

5. In OAuth Scopes, add both required scopes:
   • Access MCP servers (mcp_api)
   • Perform requests at any time (refresh_token)
6. Under Security, configure token generation:
   • Select Issue JSON Web Token (JWT)-based access tokens for named users.
   • Deselect all other optional security checkboxes that do not require Salesforce Support intervention (unless you are configuring a web-based client like ChatGPT that requires a Client Secret).
7. Click Create.
8. Open the Settings tab, expand OAuth Settings, and click Consumer Key and Secret to copy your Consumer Key (CLIENT_ID).

Build Your Hosted MCP Server URL#

Every Hosted MCP Server URL consists of three mandatory parts: the base endpoint (https://api.salesforce.com/platform/mcp/v1), an org-type or My Domain routing segment, and the prefixed server name (such as platform/sobject-all or custom/myserver).

Use the Standard Format for quick setup, or use the My Domain Format (/d/<MY-DOMAIN-NAME>/...) if your org blocks logins from generic login.salesforce.com or test.salesforce.com endpoints.

Concrete URL Examples for platform/sobject-all#

• Production (Standard): https://api.salesforce.com/platform/mcp/v1/platform/sobject-all
• Production (My Domain mycompany): https://api.salesforce.com/platform/mcp/v1/d/mycompany/platform/sobject-all
• Developer Edition (mycompany-dev-ed): https://api.salesforce.com/platform/mcp/v1/d/mycompany-dev-ed/develop/platform/sobject-all
• Sandbox (uat on mycompany): https://api.salesforce.com/platform/mcp/v1/d/mycompany--uat/sandbox/platform/sobject-all
• Scratch Org (mycompany-dev-ed): https://api.salesforce.com/platform/mcp/v1/d/mycompany-dev-ed/scratch/platform/sobject-all

Connect and Test MCP Clients#

Before initiating OAuth from any MCP client, prepare your browser session to avoid multi-tenant routing conflicts.

Mandatory Browser Pre-Authentication Step#

Because the MCP specification does not natively disambiguate multi-tenant browser sessions, complete these three steps before clicking Connect in your client:

1. Log out of all other Salesforce orgs in your default web browser.
2. Log in to the exact target org where you enabled the MCP server and External Client App.
3. Keep that browser window open so the MCP client’s OAuth redirect opens a tab in the same authenticated window.

Connect Postman (Recommended First Test)#

Always verify a new server in Postman before wiring up an LLM client. Because the Hosted MCP Server is deterministic, Postman lets you inspect raw JSON-RPC tools/call responses without an AI model interpreting or masking errors.

1. In Postman, create a new MCP request, switch the transport dropdown from STDIO to HTTP, and paste your server URL.
2. Open the Authorization tab, choose OAuth 2.0, and set Add authorization data to to Request Headers.
3. Configure a new token with these exact settings:
   • Header Prefix: Bearer
   • Grant Type: Authorization Code (With PKCE)
   • Auth URL: https://login.salesforce.com/services/oauth2/authorize (Production/DE) or https://test.salesforce.com/services/oauth2/authorize (Sandbox/Scratch), or substitute your https://<my-domain>.my.salesforce.com host.
   • Access Token URL: https://login.salesforce.com/services/oauth2/token (or test.salesforce.com / My Domain host).
   • Client ID: Your External Client App Consumer Key.
   • Client Secret: Leave blank (PKCE replaces the secret for desktop flows).
   • Code Challenge Method: SHA-256
   • Scope: mcp_api refresh_token
   • Client Authentication: Send client credentials in body
4. Click Get New Access Token, complete browser authorization, and click Use Token.

Connect Claude, ChatGPT, and Agentforce Vibes#

• Claude (Claude.ai, Desktop, and Claude Code): Navigate to Customize → Connectors → Add → Add custom connector. Enter your server URL, choose Use your own OAuth client, paste your ECA Consumer Key in OAuth Client ID, leave the secret blank, and click Connect. Connections configured in Claude Desktop or Web are automatically inherited by Claude Code.
• ChatGPT (Developer Mode): Navigate to Settings → Apps → Create App, enter your server URL, and open Authentication → Advanced settings. Choose User-defined OAuth client, copy the generated Callback URL into your Salesforce ECA, provide both the Consumer Key and Consumer Secret (ChatGPT marks the secret optional, but Salesforce requires it for ChatGPT’s web flow), and uncheck OIDC enabled.
• Agentforce Vibes (VS Code): No External Client App is needed. Open a Salesforce DX project connected to your default org, open the Agentforce Vibes → Toolkit → MCP Servers panel, locate your server under Salesforce Platform, and toggle it on.

Example#

To connect Cursor to a sandbox or scratch org running the platform/sobject-all server, open Cursor Settings → Tools & MCP → New MCP Server and configure mcp.json:

{
  "mcpServers": {
    "Salesforce": {
      "url": "https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all",
      "auth": {
        "CLIENT_ID": "3MVG9_YOUR_ECA_CONSUMER_KEY"
      }
    }
  }
}

Once connected in Postman or an MCP inspector, test authentication with the zero-parameter getUserInfo tool before running a parameterized soqlQuery call:

{
  "method": "tools/call",
  "params": {
    "name": "getUserInfo",
    "arguments": {}
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "soqlQuery",
    "arguments": {
      "query": "SELECT Id, Name, Type, Industry, AnnualRevenue FROM Account WHERE Name = 'Abbott Insurance' LIMIT 10"
    }
  }
}

Harden Security and Troubleshoot Connections#

Before rolling out Hosted MCP Servers to production users, apply defense-in-depth policies on your External Client App and establish API log monitoring.

Production Security Checklist#

• Start with least-privilege servers: Deploy platform/sobject-reads or a curated custom MCP server before granting mutation or delete tools.
• Require Permission Set pre-authorization: By default, any org user can authenticate through an ECA. In External Client App → OAuth Policies, require a custom Permission Set for pre-authorization and assign it only to approved users.
• Shorten Refresh Token lifetime: In OAuth Policies, change Refresh Token Validity from indefinite to 30 days or less and enable Refresh Token Rotation so each refresh invalidates the prior token.
• Enable Single Logout: In the ECA Session Settings, enable Single Logout so revoking a user’s Salesforce session immediately terminates their active MCP client token.
• Enforce Client Secrets only for web clients: Enable Require Secret for Web Server Flow only for server-backed web clients (such as ChatGPT). Never embed client secrets in desktop apps where binaries can be decompiled.
• Audit MCP traffic in API logs: Every MCP tool execution is recorded under the authenticated user. Filter standard Salesforce API logs or Event Monitoring where API_CLIENT_CATEGORY equals SALESFORCE_HOSTED_MCP.

Troubleshooting Matrix#

Limits and Gotchas#

• ECA propagation time: Up to 30 minutes after creating or modifying an External Client App before OAuth endpoints recognize it.
• Server activation latency: Up to 2 minutes after toggling an MCP server on in Setup.
• No service accounts or headless flows: Hosted MCP Servers enforce interactive OAuth 2.0 Authorization Code with PKCE exclusively. Client Credentials, JWT Bearer headless flows, and dynamic client registration are not supported.
• IP allowlist capacity: Some cloud-hosted AI clients use dynamic egress IP ranges that exceed Salesforce’s OAuth IP allowlist capacity. Verify vendor IP stability before enabling IP restrictions on the ECA.
• Deterministic server execution: Hosted MCP Servers do not run an LLM for standard tool execution; they translate MCP tools/call requests directly into governed Salesforce platform operations.

Related Official Documentation#

• Salesforce Hosted MCP Servers Developer Guide: official setup, authentication, and client configuration reference.
• Salesforce MCP Servers Release Notes: GA changes, supported servers, and release updates.
• Connect Claude with Salesforce Hosted MCP Servers: step-by-step walkthrough for Anthropic Claude connectors.

Frequently asked questions

Why does Salesforce require an External Client App instead of a Connected App for Hosted MCP Servers?

Hosted MCP Servers only support External Client Apps because ECAs enforce modern OAuth 2.0 security controls, including mandatory PKCE, named-user JWT access tokens, and packageable metadata separation. Legacy Connected Apps are rejected during MCP authentication.

What OAuth scopes and token settings are required for Hosted MCP Servers at GA?

Configure your External Client App with two OAuth scopes: mcp_api and refresh_token. In the ECA Security settings, enable Issue JSON Web Token (JWT)-based access tokens for named users and use the Authorization Code flow with SHA-256 PKCE.

Do Hosted MCP Servers use a shared integration user or per-user permissions?

Every MCP tool call runs in the authenticated user's context using the OAuth 2.0 Authorization Code flow. Agents inherit the user's exact object CRUD, field-level security, and sharing rules. Headless machine-to-machine or shared service account flows are not supported.

Why must I log out of other Salesforce orgs in my browser before authenticating an MCP client?

The Model Context Protocol specification does not natively handle multi-tenant session routing during browser OAuth handshakes. Logging into only your target org in the default browser prevents the OAuth callback from binding to the wrong active Salesforce session.

How do I audit and monitor AI agent activity coming from Hosted MCP Servers?

All MCP tool executions are logged under the authenticated user's ID in standard Salesforce API logs. Filter your API log files or Event Monitoring queries where API_CLIENT_CATEGORY equals SALESFORCE_HOSTED_MCP to isolate and audit every agent action.

How do I test Hosted MCP Servers in a scratch org if I cannot create an External Client App in Setup?

Scratch orgs do not allow creating External Client Apps directly in the Setup UI. Create the External Client App in your Dev Hub org, add it to a package, and install that package into your target scratch org before connecting your MCP client.

What changed between the Salesforce Hosted MCP beta and the GA release?

Three breaking changes occurred at GA: the endpoint path changed from v1-beta.2 to v1, MCP servers are disabled by default and must be activated in Setup under API Catalog, and the four beta OAuth scopes were consolidated into mcp_api and refresh_token.

When should I enable a Client Secret on the External Client App for MCP?

Enable Require Secret for Web Server Flow only for server-hosted web clients like ChatGPT that store secrets securely on a backend. Do not require a client secret for desktop clients like Cursor or Postman desktop, which rely on PKCE without a secret.