Skip to Content
GuidesMCP GatewaysAdd remote MCP serversSalesforce

Connect a Salesforce Hosted MCP Server

Salesforce can host an MCP server  for an org, exposing tools such as SOQL queries directly from Salesforce data. This guide covers the Arcade-side setup for connecting a Salesforce Hosted Server as a remote MCP server, plus the handful of Salesforce settings that most commonly trip people up.

This guide is about connecting to a Salesforce Hosted Server. If you’re looking to call Salesforce APIs from your own instead, see the Salesforce auth provider guide.

Outcomes

Connect a Salesforce Hosted Server to Arcade and use its in gateways and SDKs.

You will Learn

  • Which Salesforce External Client App settings matter for Arcade specifically, and why
  • Configure the remote server’s OAuth 2.0 settings in Arcade
  • Diagnose the most common setup mistakes from their error messages

Prerequisites

Set up Salesforce

Follow Salesforce’s own guides to create your Hosted MCP Server , activate it , and create an External Client App  (ECA) for it. A few settings on the ECA matter specifically for connecting to Arcade:

  • OAuth Scopes: include mcp_api. Salesforce’s guide lists this scope without explaining why it’s required; without it, authorization succeeds, but every call fails with a 401.
  • Issue JSON Web Token (JWT)-based access tokens for named (under Security). Salesforce’s guide instructs you to enable this without saying why. Without it, Salesforce issues an opaque session token instead of a JWT, and the Hosted Server’s endpoint only validates JWTs: every call fails with a bare {"errors":[{"message":"Invalid token"}]} 401, even though authorization otherwise looks successful.
  • Require PKCE: Salesforce’s ECA guide doesn’t mention PKCE at all, but Arcade always uses it (RFC 7636, S256) when authorizing against a remote server. Leave PKCE enabled on the ECA (it’s on by default).
  • Callback URL: set this once you have the redirect URI Arcade generates (see Add the redirect URI to your ECA below). You can use a placeholder now and come back to it.

Configure the remote server in Arcade

Register the server

Go to the MCP servers dashboard , click Add server, and enter a server ID and the Hosted Server’s URL (it looks like https://api.salesforce.com/platform/mcp/v1/custom/YourServerName).

Configure OAuth2 authorization

Open Advanced settings → OAuth2 authorization and enter:

  • Client ID / Client Secret: your ECA’s Consumer Key and Consumer Secret.
  • Authorization URL: the full OpenID Connect discovery URL for your org, not just the bare domain: take your org’s My Domain URL (find it under Salesforce Setup → My Domain) and append /.well-known/openid-configuration. For example, https://acme-inc.my.salesforce.com/.well-known/openid-configuration. Arcade fetches this URL to discover the real authorization and token endpoints. Don’t use the ECA’s /authorize path or api.salesforce.com: neither serves that discovery document.

Salesforce Hosted Servers don’t support Dynamic Client Registration, so you must supply the Client ID and Secret manually. If you leave these blank, Arcade attempts Dynamic Client Registration and Salesforce rejects it.

Add the redirect URI to your ECA

Copy the redirect URI Arcade generated and set it as the ECA’s Callback URL. A new server registration gets its own unique redirect URI, so update the Callback URL again if you ever re-register the server under a new ID.

Authorize and confirm

Save the server and complete the authorization prompt. On the scope selection screen, confirm mcp_api is checked — Arcade lists every scope your org’s discovery document advertises as supported, not just the ones your ECA actually grants, so only select scopes your ECA has enabled.

Don’t refresh the Arcade dashboard while an authorization prompt is open. Refreshing mid-flow can leave a stale, incomplete authorization behind instead of cleanly restarting it. If a connection seems stuck, close the prompt, reload the page, and start a single fresh attempt.

Troubleshooting

  • A 401 with {"errors":[{"message":"Invalid token"}]} and no error code: your ECA isn’t issuing JWT-based access tokens. See Set up Salesforce.
  • Authorization succeeds, but calls 401: the mcp_api scope is missing from either the ECA’s Selected Scopes or the scopes you approved during authorization.
  • list is empty or every call fails: confirm the Hosted Server is activated .
  • A setting change doesn’t seem to take effect: existing tokens don’t retroactively pick up new ECA settings. In Salesforce Setup, go to the affected ’s OAuth Apps list and revoke the existing grant, then re-authorize to get a fresh token.

Next steps

Last updated on
OverviewCreate via Dashboard