Skip to main content
No longer maintained. This Runlayer-built connector is deprecated and will not receive further updates. Use Salesforce’s official hosted MCP servers instead. See the Salesforce hosted MCP guide.The two need different OAuth scopes, and picking the wrong one fails in a way that looks like everything worked:The hosted one additionally needs Issue JSON Web Token (JWT)-based access tokens enabled on the External Client App. Without it Salesforce mints an opaque session token, api.salesforce.com rejects it with Invalid token, and nothing in the OAuth flow hints at why.
Connect your AI assistant to Salesforce for CRM data queries, record management, and schema exploration. Uses Salesforce OAuth for authentication.

​
Available Tools

​
Setup

1

Create the app in Salesforce

  1. In Salesforce Setup, search for External Client App Manager (newer orgs) or App Manager (older orgs)
  2. Click New External Client App (or New Connected App)
  3. Fill in:
    • External Client App Name: Runlayer MCP
    • Contact Email: your email
    • Distribution State: Local (the app is only used by your own org)
  4. Expand API (Enable OAuth Settings) and check Enable OAuth
  5. Callback URL: https://<your-tenant>.runlayer.com/oauth/callback — no trailing slash, Salesforce matches it exactly
  6. Selected OAuth Scopes — add exactly these two:
  7. Under Flow Enablement, enable Authorization Code and Credentials Flow
  8. Leave Require secret for Web Server Flow on — Runlayer uses the client secret
  9. Click Create / Save
Do not pick mcp_api for this connector. “Access Salesforce hosted MCP servers (mcp_api)” is for Salesforce’s own hosted MCP servers, which are a different connector. With mcp_api alone the OAuth flow completes, the token introspects as active, and everything looks connected — but every call fails with INVALID_AUTH_HEADER: INVALID_SCOPES.Older versions of this page said to select Full access (full). That scope belongs to classic Connected Apps and isn’t offered in the External Client App picker; api is the correct choice and grants strictly less.
A new app can take up to 10 minutes to propagate before it will authorize.
2

Get the Consumer Key and Secret

  1. Open the app you just created
  2. Go to Settings → OAuth Settings and click Consumer Key and Secret (older UI: Manage Consumer Details)
  3. Re-authenticate if prompted, then copy the Consumer Key (Client ID) and Consumer Secret (Client Secret)
Only see the key and not the secret? In the External Client App Manager the secret is gated behind a user permission — see the troubleshooting entry below.
3

Add Server in Runlayer

  1. In Runlayer, go to My connectors, find Salesforce, and click Add connector
  2. Check Custom OAuth credentials
  3. Enter your Client ID and Client Secret
  4. If connecting to a sandbox org, set Login URL to https://test.salesforce.com
  5. Click Deploy Server
4

Authorize

  1. Click Connect on the server page
  2. Log in with your Salesforce credentials
  3. Check the consent screen lists the permissions you selected, then click Allow
Each user authorizes with their own Salesforce credentials. Queries and operations run with that user’s permissions and field-level security.
Changing scopes later requires a reconnect, not just an app edit. Salesforce records the granted scopes in the token at authorization time, so an existing connection keeps refreshing with the old set no matter what the app now allows. After changing scopes, come back here and click Reconnect (or Profile → My Accounts → Salesforce → Reconnect) to mint a new token.

​
Configuration Reference

Required: Optional:

​
Troubleshooting

The token was issued without the scope this connector needs. It calls the classic REST/SOQL API, so the app must grant Manage user data via APIs (api). Access Salesforce hosted MCP servers (mcp_api) is for Salesforce’s own hosted MCP servers and does not work here — with only that scope, OAuth completes and the token introspects as active while every call still fails.Fixing it takes two steps, and the second is the one people miss:
  1. Add the api scope to the app in External Client App Manager → your app → Settings → OAuth Settings
  2. Reconnect the account in Runlayer. Salesforce records granted scopes in the token, so the existing connection keeps refreshing with the old set until it is re-authorized. Editing the app alone changes nothing.
If the consent screen doesn’t show the new permission, the app change hasn’t propagated yet — wait a few minutes and retry.
Verify the callback URL in your Connected App matches exactly: https://<your-tenant>.runlayer.com/oauth/callback (no trailing slash for Salesforce).
The Connected App must be created in the same org you are authenticating against. External Client Apps do not support cross-org OAuth flows.
Salesforce Connected Apps can take up to 10 minutes to propagate. Wait and retry the authorization.
Your Salesforce access token has expired (tokens last ~2 hours). Reconnect in Runlayer to get a fresh token. If you have refresh_token scope enabled, this should happen automatically.
In the External Client App Manager, the Consumer Secret is gated behind a user permission. If you only see the Consumer Key, your user is missing the required permission on the External Client App.Grant your user the Create, edit, and delete External Client Apps permission (and View External Client App Consumer Secrets in Metadata if you also need metadata access), then revisit the app’s detail page and click Manage Consumer Details to reveal both the key and secret. See the Salesforce help article on External Client App user permissions for the full list.