Skip to main content
Clientell AI MCP / Troubleshooting

Why can’t I connect Claude, Cursor or Codex to Salesforce?

Two separate connections can break. Your AI client has to reach the Clientell AI server, which fails on a bad token or URL. Then Clientell AI has to sign in to Salesforce, which fails on API access, a sandbox login URL, app approval, IP rules or multi-factor authentication (MFA). Test the first one first. It takes ten seconds.

Book a call with an expert Start the 14-day trialFull setup documentation
Start here

Which connection is failing?

Claude, Cursor and Codex talk to the Clientell AI server. Clientell AI then talks to your org. Test the first link before you touch Salesforce.

Terminal
curl -I https://mcp.clientell.ai/mcp

A 401 or 403 means the server is up and wants a valid token. A 404 or 405 also means it is up, because MCP endpoints answer POST and not HEAD. No response means a wrong URL, DNS, or something on your network. On Windows PowerShell use curl.exe.

Claude Code gives a better check. Run claude mcp get clientell. If the status is connected and your client lists the tools, the first link works, and what is left is the Salesforce sign-in below. If it prints an Issue: line, that line carries the HTTP status and the server’s own error text.

Client to server

What breaks between your AI client and the server?

Nearly all of it is the token or the URL. Per client:

  • Claude Code: a 401 is usually a space or newline copied with the token. If claude mcp list does not show the server, the entry has no "type": "http". The message MCP endpoint not found means the URL does not end in /mcp.
  • Cursor: the same stray space gives a 401. After you edit mcp.json, reload the Cursor window.
  • Codex: the token lives in the CLIENTELL_MCP_TOKEN variable, so the shell that starts Codex must have it set.
  • VS Code: the top-level key is servers, not mcpServers, and a workspace in Restricted Mode will not start the server.
  • Claude Cowork: the Authorization header must read Bearer <YOUR_TOKEN> with the word and the space.
Server to Salesforce

Why does the Salesforce sign-in fail?

Clientell AI sends you to Salesforce in your browser to sign in with OAuth, the standard sign-in handshake. These errors show up in that browser window or just after it. The OAuth error names are Salesforce’s, from its OAuth error reference.

external_app_not_installed
What it means

The Clientell AI managed package is not in the org you are connecting. Salesforce reports it as OAUTH_EC_APP_NOT_FOUND: the app being authorized does not exist there.

Fix

Install the package in that org. It takes an admin about two minutes, and the production and sandbox install links are in Check 5 of the setup documentation. Packages install per org, so production can have it while the sandbox does not, and the error looks the same either way.

Sign-in works, but the connection cannot read the org
What it means

The person who authorized has no API access. Salesforce requires the API Enabled permission on the user's profile for any API call.

Fix

In Setup, open that user’s profile and turn on API Enabled. Many standard profiles have it on already. Check the edition first. API access is on by default in Enterprise, Performance, Unlimited and Developer Edition. Professional Edition has to add it. If you are on Professional and the checkbox changes nothing, the org does not have the add-on, and no profile edit will fix that.

The rules are in Salesforce’s REST API editions and permissions page.

Connecting a sandbox fails at the Salesforce sign-in
What it means

Sandboxes do not sign in through login.salesforce.com.

Fix

Salesforce says to always log in to a sandbox with its My Domain login URL or with https://test.salesforce.com. The My Domain form is MyDomainName--SandboxName.sandbox.my.salesforce.com, and the My Domain Setup page shows yours. After a sandbox is created or refreshed, test.salesforce.com can take 24 to 48 hours to work, so use the My Domain URL in the meantime. If the My Domain option Prevent login from https://test.salesforce.com is on in the sandbox, only the My Domain URL works at all.

Also check who you are signing in as. A refresh deletes sandbox-only users and resets everyone else’s access to what production has. If the connection worked last week and fails after a refresh, check that the package is in the sandbox and that the user still has API Enabled. Source: Sandbox Access Considerations.

invalid_app_access, or invalid_grant with “user hasn’t approved the connected app”
What it means

An admin set the app's Permitted Users to admin-approved, and the user's profile or permission set is not on the list.

Fix

In Setup, open Manage Connected Apps, edit the app, and look under OAuth Policies at Permitted Users. If it says Admin approved users are pre-authorized, add the profile to the app’s Connected App Access list, or add the app to a permission set the user has. We would do it that way and leave the policy alone. Salesforce also lets anyone with the Use Any API Client permission through, and its own Help page warns that this gives up your control over authorization. Details: Manage OAuth Access Policies for a Connected App. For the wider picture, read the Spring ’26 connected app changes.

invalid_grant with “IP restricted or invalid login hours”
What it means

The user's profile has login IP ranges or login hours, and the request came from outside them.

Fix

Salesforce enforces IP restrictions only if they are set on the profile, so check the profile first. If you want the app to keep working from a server, the app’s IP Relaxation setting has an option called Enforce IP restrictions, but relax for refresh tokens. We would pick that over Relax IP restrictions, which drops the org’s IP rules for the app altogether. It is your admin’s call, and it is the same OAuth Policies page.

Stuck at a verification code or an authenticator prompt
What it means

The sign-in in your browser is a UI login, and Salesforce enforces MFA on UI logins.

Fix

Salesforce has required MFA for UI logins since 2022, and from 20 July 2026 it turns the enforcement setting on in production orgs. That can hit integrations that sign in through a browser. It does not require MFA for integration login types over the API. So the person authorizing needs an MFA method registered before they start, and the Salesforce step has a ten-minute window. Have the phone or key in your hand, then go. If it times out, ask your AI client for a fresh connect link. Source: Multi-Factor Authentication for API Access.

connect_expired, authorization_expired or oauth_session_mismatch
What it means

The connect link is single-use and lasts 30 minutes, the Salesforce step has ten minutes, and the browser must be signed in to the same Clientell AI account that asked for the link.

Fix

Go back to the terminal or chat, ask your coding agent to connect Salesforce again, and open the new link in the same browser profile. Do not reuse an old link. For oauth_session_mismatch, sign in to Clientell AI with the account your agent uses first.

A connection that worked and then stops weeks later has a different cause. The app’s Refresh Token Policy decides how long a refresh token lives, and an admin can set it to expire after a fixed time or after a period unused. Reconnect Salesforce in the Clientell AI web app.

Dates to know

Do the Salesforce OAuth changes in 2026 and 2027 affect this?

Probably not the Clientell AI connect step, which is a normal browser sign-in. They hit your own scripts, so it is worth a look while you are in here.

  • 30 November 2026. Salesforce blocks the OAuth device flow for connected apps, packaged external client apps, and local external client apps without a localhost callback URL. After that it works only for local external client apps with a localhost callback. It applies in all editions. Salesforce says the flow is meant for devices with limited input, such as smart TVs. Source: Restrict the OAuth 2.0 Device Flow (release update).
  • 20 February 2027. The OAuth username-password flow stops working for connected apps. Salesforce moved this date from Winter ’27, and orgs created in Summer ’26 or later already block the flow. The replacements it names are the web-server flow with PKCE for people and the client credentials flow for servers. Source: Retirement of OAuth 2.0 Username-Password Flow (release update).

If a CI job or a shell script logs in to an org with either flow, it breaks on those dates. See the connected app glossary entry for the terms, and the sandbox entry if you test in one first.

FAQ

Questions people ask.

Why can't I connect Claude to Salesforce?

Two links can break. Either Claude cannot reach the Clientell AI server, which means a wrong token or URL, or Clientell AI cannot sign in to your org. For the second, the usual causes are a missing managed package, a user without API Enabled, the wrong login URL for a sandbox, an app approval policy, IP restrictions and MFA.

Do I need API Enabled to connect an AI agent to Salesforce?

Yes, for the user who authorizes the connection. Salesforce says any API call needs the API Enabled permission on the user's profile. Enterprise, Performance, Unlimited and Developer Edition include API access by default. Professional Edition can add it.

How do I connect an AI tool to a Salesforce sandbox?

Sign in to the sandbox through its My Domain URL, which looks like MyDomainName--SandboxName.sandbox.my.salesforce.com, or through test.salesforce.com. Never use login.salesforce.com for a sandbox. Install the Clientell AI package in the sandbox itself, because packages are installed per org.

Does MFA block the connection?

The Salesforce sign-in in your browser is a UI login, and Salesforce enforces MFA on UI logins. Salesforce does not require MFA for integration login types over the API. The person who authorizes needs to have registered an MFA method before they start.

Will the 30 November 2026 device flow change break my connection?

Not the Clientell AI connect step, which is a browser sign-in. The change matters if your own scripts log in to orgs with the OAuth device flow through a connected app. From 30 November 2026, Salesforce blocks that unless the app is a local external client app with a localhost callback URL.

Why did the Salesforce DX MCP server stop working?

Salesforce ended support for it on 2 November 2026. The npm package stays installable and a pinned 0.30.15 setup keeps running, but no more releases ship. Salesforce points developers to skills at forcedotcom/sf-skills.

Keep going

Related pages.

Sources: Salesforce OAuth error reference, Manage OAuth Access Policies for a Connected App, REST API supported editions and permissions, Sandbox Access Considerations, Multi-Factor Authentication for API Access, device flow release update, username-password flow release update (all Salesforce, checked 4 Nov 2026), Salesforce DX MCP end-of-life notice, Clientell AI MCP documentation. Last reviewed November 2026.