Connect Claude Code, Claude Desktop & Codex

• MCP has to be switched on for this deployment. If the MCP access card in Settings shows a warning instead of a form, an operator needs to enable it first.
• At least one connected Salesforce org — see Connect your Salesforce orgs. No client can connect an org for you; that needs a browser sign-in.
• The client installed and signed in to its own AI subscription. Your subscription pays for the thinking; orgadmin.ai only supplies the Salesforce tools, so no AI key is needed here.

Every client below authenticates the same way, so do this once. In Settings → MCP access:

1. 1

   Name it after the machine that will use it

   Claude Code on my laptop, work desktop. This is what you look for when you revoke one later.
2. 2

   Tick only the scopes you need

   org:read alone covers reading schema, code, flows, debug logs and SELECT-only SOQL, which is most work. A tool outside your scopes is never even shown to the AI. The full breakdown is in the MCP guide.
3. 3

   Copy the token before you leave the page

   It is shown once and stored only as a hash — nobody can show it to you again. Lose it and you revoke it and make another.

One command adds the server to every project on your machine. Works the same in the CLI, the desktop app, and the VS Code and JetBrains extensions.

1. Add the server — --scope user makes it available in every project. Drop it to add the server to the current project only.

   claude mcp add --transport http --scope user orgadmin https://orgadmin.ai/api/mcp --header "Authorization: Bearer oamcp_your-token-here"

2. Check it connected — Should report "Connected". Inside a session, /mcp shows the same thing plus the tool list.

   claude mcp list

3. Sharing a repo instead? Use .mcp.json — Claude Code expands ${ORGADMIN_MCP_TOKEN} at load time, so this file is safe to commit — each teammate sets their own token in their environment and holds their own scopes.

   In .mcp.json:

   {
     "mcpServers": {
       "orgadmin": {
         "type": "http",
         "url": "https://orgadmin.ai/api/mcp",
         "headers": {
           "Authorization": "Bearer ${ORGADMIN_MCP_TOKEN}"
         }
       }
     }
   }

Two things worth knowing:

• Tools appear with an mcp__orgadmin__ prefix — that's Claude Code namespacing them, not a different tool set. Ask in plain English; you never type the names.
• The ready-made prompts show up under / — explore_org, investigate_error, security_review and build_metadata. They carry the ordering knowledge (check automation before proposing a trigger, confirm field names before writing SOQL) that otherwise only the in-app assistant has.

Claude Desktop installs extensions rather than reading a URL, so Settings builds you one: a .mcpb file containing a small local bridge and your token. Download it, double-click it, done — there is no config file to edit and nothing to paste.

1. Download the extension — In Settings → MCP access, create a token and click "Download Claude Desktop extension". Your token is packaged inside it, so there is nothing to configure after installing.
2. Install it — Double-click the .mcpb file, or drag it onto the Claude Desktop window. You can also use Settings → Extensions → Advanced settings → Install Extension…. Claude Desktop may warn that it did not come from its directory, which is expected for a bundle you built yourself. Replacing an existing install: remove the old extension first, since the new file differs only by the token inside it.
3. Other stdio-only clients: run the bridge directly — Use --probe first to confirm it reaches the server; it performs the handshake, prints what the server offers, and exits. In PowerShell, set the variable with $env:ORGADMIN_MCP_TOKEN = "…" instead of export.

   export ORGADMIN_MCP_TOKEN="oamcp_your-token-here"
   node scripts/mcp-stdio.mjs --url https://orgadmin.ai/api/mcp --probe

4. …then point the client at it — Use the absolute path to the bridge — these clients do not run in your shell and will not resolve a relative one.

   In the client’s MCP config:

   {
     "mcpServers": {
       "orgadmin": {
         "command": "node",
         "args": [
           "/absolute/path/to/scripts/mcp-stdio.mjs",
           "--url",
           "https://orgadmin.ai/api/mcp"
         ],
         "env": {
           "ORGADMIN_MCP_TOKEN": "oamcp_your-token-here"
         }
       }
     }
   }

Codex reads its MCP servers from ~/.codex/config.toml and takes the token from an environment variable, so the credential never lands in the config file itself.

1. Put the token in your environment — macOS and Linux — add it to ~/.zshrc or ~/.bashrc so it survives a new terminal. On Windows, use setx ORGADMIN_MCP_TOKEN "…" and open a new terminal.

   export ORGADMIN_MCP_TOKEN="oamcp_your-token-here"

2. Add the server — Append this to your Codex config. Codex reads the token from the environment variable at connect time.

   In ~/.codex/config.toml:

   [mcp_servers.orgadmin]
   url = "https://orgadmin.ai/api/mcp"
   bearer_token_env_var = "ORGADMIN_MCP_TOKEN"
   # The first connection wakes the deployment and re-checks your token,
   # which can take longer than the 10s Codex allows by default.
   startup_timeout_sec = 30

3. Check it connected — Lists the server and its tools. /mcp inside a session shows the same, and names the failure if it did not connect.

   codex mcp list

Two things worth knowing:

• The variable has to be set where Codex starts. Codex reads it from its own environment at connect time, so putting it in ~/.zshrc (or setx on Windows) and opening a new terminal is the reliable way — exporting it in a shell Codex is already running in does nothing.
• Codex uses tools and the server's instructions. The prompts and resources this server also publishes are surfaced by clients that support them, such as Claude Code; in Codex you just ask for what you want.

Whichever client you used, ask it to “use the whoami tool”. It comes back with the orgadmin.ai account the connection is authenticated as, the token's name, and the exact scopes it was granted:

{
  "account": { "email": "[email protected]", "name": "Your Name" },
  "token": { "name": "Claude Code on my laptop" },
  "scopes": ["org:read"]
}

That single call proves the server is reachable, the token is valid, and which permissions it carries — which is also the fastest way to explain a surprising “tool not found” later. Then try a real one:

• “List my connected Salesforce orgs.”
• “What fields are on Opportunity in my sandbox?” — you can name an org the way you named it here; there is no need to paste an id.
• “What automation runs on Account, and is any of it likely to conflict?”

Claude Code

• “Failed” in /mcp rather than an offer to sign in — Claude Code reports a rejected Authorization header as a failed connection instead of falling back to a sign-in flow. It means the token is wrong, revoked or expired, not that the server is down. Add the server again with a fresh token.
• The server is missing in another project — it was added without --scope user, so it belongs to the directory you ran the command in. Add it again with that flag.
• It tries to run the URL as a program — --transport http was left out, so the CLI read the URL as a command to execute.

Claude Desktop

• The download button is greyed out — the extension can only be built while a freshly created token is on screen, since that is the only moment the token exists in readable form. Create one and it lights up.
• It installs, then every tool fails — the token inside it was revoked or expired. A bundle can't be re-keyed: create a new token, download a fresh extension, and remove the old extension first. Two downloads differ only by the token inside them, so installing over the top can leave the old one running.
• A warning that it isn't from the extension directory — expected for a bundle built by your own deployment rather than published to Anthropic's directory.

Codex CLI

• It gives up while starting the server — the first connection wakes the deployment and re-checks your token, which can take longer than the ten seconds Codex allows by default. Raise startup_timeout_sec in the server's block.
• It connects but lists no tools — the variable named by bearer_token_env_var isn't set in the environment Codex was launched from. Set it, then restart Codex rather than just starting a new session.

Any client

• A tool this page mentions is “not found” — your token doesn't hold its scope, so it was never offered. Scopes are fixed when a token is created; make a new one. whoami shows what you have.
• 404 on the endpoint — MCP is switched off for this deployment.
• Everything worked, then stopped — a revoked token, a deactivated account, or a Salesforce sign-in revoked upstream all cut access off on the very next call, mid conversation.

Server-side messages — rate limits, sandbox-only writes, results too large — are covered in the MCP guide's troubleshooting section.