How to Connect Claude to Salesforce Through Hosted MCP Servers
- Kris Var
- 11 minutes ago
- 7 min read
Salesforce's own documentation for connecting an AI client to an org through MCP (Model Context Protocol) runs across six separate pages: a setup overview, creating an External Client App, activating a server, connecting a client, testing the connection, and troubleshooting if something goes wrong. There's a seventh page written specifically for Claude, with its own callback URL and its own screenshots. None of these tie together into one sequence, and none of them cover the CLI path, Claude Code, at all; the Claude-specific page only walks through the browser-based connector in Claude.ai and Claude Desktop.
If you want the industry vocabulary first, see what "agent harness" means and how MCP fits into it. This piece skips straight to mechanics: what to click, what to type, and in what order, to connect Claude to Salesforce, on both surfaces.
Before you start
System Administrator permission (or equivalent) to create an External Client App in Setup. If that's not you, Steps 1 and 2 are someone else's job; everything from Step 3 onward only needs the Consumer Key and server URL they hand you.
Enterprise Edition or above. Hosted MCP Servers reached general availability on April 29, 2026.
On the Claude side, custom connectors using remote MCP work on every plan, including Free, per Anthropic's own support documentation, so no upgrade is needed just to follow this guide.
Decide which Claude surface you're connecting before you start Step 1, since Claude.ai/Claude Desktop and Claude Code use different OAuth callback URLs. This isn't a permanent fork, though: one External Client App can hold more than one callback URL, so supporting both surfaces later just means coming back to add the second one, not starting over.
Step 1: Create an External Client App
Hosted MCP Servers authenticate through External Client Apps, a different object from the older Connected App type. Connected Apps aren't supported for this.
1. In Setup, use Quick Find to search "external client," then open External Client App Manager. Click New External Client App.
2. Fill in the Basic Information (name, contact email).
3. Expand API (Enable OAuth Settings) and check Enable OAuth.
4. Set the Callback URL. For Claude, that's https://claude.ai/api/mcp/auth_callback, whether you're using Claude.ai in a browser or Claude Desktop. Other clients use different values here, which is why deciding on a client first matters: Cursor's callback URL is http://localhost:8787/callback, Postman's is https://oauth.pstmn.io/v1/callback.
5. Under OAuth Scopes, add "Access MCP servers" (mcp_api) and "Perform requests at any time" (refresh_token).
6. Under Security, select "Issue JSON Web Token (JWT)-based access tokens for named users" and leave the other optional settings unchecked.
7. Click Create.
Activation isn't instant. Salesforce's own documentation notes it can take up to 30 minutes and compares the delay to DNS propagation, worth knowing so a connection attempt failing five minutes after you click Create doesn't send you back through the setup looking for a mistake that isn't there.
Once it's active: open the app, click Settings, then under OAuth Settings click Consumer Key and Secret, and copy the Consumer Key. That's what you'll paste into Claude in Step 3.
Hardening it beyond a first test: the settings above are enough to get a connection working, not enough for a production rollout with more than one person using it. Salesforce's own guidance for this page lists a few worth revisiting before that: requiring a client secret for web-based clients, restricting the app to specific users through a required Permission Set, IP restrictions, shortening the refresh token lifetime with rotation (30 days), and single logout.
Step 2: Activate a Hosted MCP Server
Every Hosted MCP Server is off by default, org-wide. That's a deliberate gate, separate from creating the External Client App above, not a step you can skip because the app already exists.
Which server to start with
Salesforce ships four standard SObject servers, plus a handful of product-specific servers (Data 360, Tableau Next, and a beta Headless 360 server) that are out of scope for this walkthrough:
platform/sobject-reads: query and read only. No create, update, or delete.
platform/sobject-mutations: create and update. No delete.
platform/sobject-deletes: delete only.
platform/sobject-all: full CRUD.
If you're not sure where to start, Salesforce's own GA announcement says so directly: start with sobject-reads in a sandbox.
Every SObject server enforces the same security model, whichever one you pick: field-level security, object permissions, and sharing rules apply to every tool call, per Salesforce's own reference for these servers. Picking sobject-all over sobject-reads doesn't hand Claude anything a user's own permission set doesn't already grant them. What changes is the blast radius: a bad prompt or a compromised session can do whatever that user's permissions already allow, and that scope grows with the server you activate. Permission Sets Reporting Helper and Fields Access Explorer are the audit for exactly this, from opposite directions: what a permission set grants, and who has access to a given field. Run one before widening a server from reads to mutations or full CRUD, not after a prompt does something you didn't expect.
1. In Setup, Quick Find "MCP Servers," under API Catalog.
2. Toggle on the server you chose above. Allow up to 2 minutes for the toggle to take effect.
Server URLs
Each server has its own endpoint, and the URL differs between production and sandbox:
Production: https://api.salesforce.com/platform/mcp/v1/<SERVER-NAME>
Sandbox or scratch org: https://api.salesforce.com/platform/mcp/v1/sandbox/<SERVER-NAME>
For example, sobject-reads in a sandbox is https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads. This is the URL that goes into Claude, or Claude Code, in the next step.
Step 3: Connect Claude
Claude.ai or Claude Desktop
1. In the left sidebar, go to Customize, then Connectors, then the + button, then Add custom connector.
2. Give it a name and, optionally, a description.
3. Server URL: paste the production or sandbox URL for whichever server you activated in Step 2.
4. Open Advanced settings and paste the Consumer Key from Step 1 into OAuth Client ID. Click Add.
5. Click Connect next to the new connector. Claude redirects to the org to complete the OAuth flow (skipped automatically if you're already logged in) and returns with an access token.
6. Optional: click Configure on the connector to restrict which tools inside that server are allowed.
Claude Code (CLI)
Nothing on Salesforce's docs site covers this path; it comes from Anthropic's Claude Code documentation instead, and it needs one extra piece Claude.ai's setup doesn't: a pre-registered client ID, passed in from the start rather than added after a failed attempt.
Claude.ai's own connector setup has you paste the External Client App's Consumer Key in as an explicit OAuth Client ID, a sign that Salesforce's OAuth server doesn't support Dynamic Client Registration, so every client needs a pre-registered ID rather than negotiating one on the fly. Claude Code's plain claude mcp add --transport http form skips that step by default, and its OAuth callback also binds to a random local port on each attempt, which won't match a fixed callback URL registered on the External Client App. Neither of those is confirmed against a live connection here, but they line up with how Salesforce's OAuth server behaves elsewhere in this setup, and with outside reports of the same failure. Save yourself the failed attempt and start with the pre-configured-credentials form:
claude mcp add --transport http --client-id <consumer-key> --callback-port <port> salesforce https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-readsReplace <consumer-key> with the Consumer Key from Step 1, and <port> with a port number of your choice (8787 is a common default). Add a matching http://localhost:<port>/callback entry to the External Client App's callback URLs, alongside the Claude.ai one from Step 1; one app can hold both.
--transport http tells Claude Code this is a remote, URL-hosted server rather than a local process it has to spawn. Registering the server doesn't sign you in yet. Run claude mcp list and you'll see salesforce marked ! Needs authentication, which is expected for any OAuth-protected server at this point. Start a session with claude, run /mcp, select salesforce, and choose Authenticate. A browser opens to the same org login and consent screen as the Claude.ai path above; approve it, and the status changes to connected.
Add --scope user instead of the default if you want the connection available across every project you work in, not just the one you're sitting in when you run the command.
claude mcp remove salesforce takes it back out.
Step 4: Test the connection
A plain natural-language prompt against real data confirms the whole chain actually works end to end: External Client App, activated server, Claude connector, OAuth, live query. Salesforce's own testing guidance suggests something as direct as "tell me some basic information about the [Account Name] account," with a real account name from the org you connected. Any of the SObject servers can answer this.
If something doesn't connect
Salesforce's troubleshooting documentation groups failures into three categories, worth knowing before digging in blind:
Server connection failures: the server URL, whether it's actually activated, API access.
Authentication issues: the External Client App's OAuth settings, a callback URL mismatch (such as pasting Cursor's callback into an app meant for Claude).
Prompt run failures: permissions, whether a feature is actually turned on, bad parameters.
Knowing which bucket a failure falls into narrows down where to look considerably faster than restarting the whole setup sequence from the top.
Where this fits
At this point Claude can read, or write, live Salesforce data through whichever server you activated. That's the mechanical half of a bigger picture. For the industry vocabulary, what "agent harness" means and how it maps onto Salesforce's own Agentforce architecture, see What 'Agent Harness' Means for a Salesforce Developer. For the broader shape of Salesforce MCP itself, both directions it runs in and what's live today, see What Admins Should Know About Salesforce MCP.
Before connecting anything broader than a read-only sandbox server, run the audit this setup just made relevant: Permission Sets Reporting Helper shows what a permission set actually grants; Fields Access Explorer shows who has access to a given field. Both are Power User Toolkit tools, and both belong before a server's scope gets widened, not after.
Comments