Your internal MCP server takes short-lived SSO tokens rather than OAuth — how do you authenticate it in Claude Code, and how does that differ from signing in through `/mcp`?
answer
- browser sign-in versus a script
- /mcp or a shell login command
- JSON object of headers on stdout
- fresh on every connection, never cached
- trust gates repository-supplied helpers
basics
~20 sSet headersHelper: a command printing a JSON object of headers, run fresh on every connection and re-run once after a 401 or 403. /mcp is for OAuth servers: Claude Code runs a browser sign-in, then stores and refreshes the tokens.
solid answer
~50 sFor an OAuth server, add it with `--transport http` and sign in from `/mcp` (or `claude mcp login <name>`, with `--no-browser` over SSH); Claude Code stores the tokens securely, refreshes them, and offers **Clear authentication** and **Re-authenticate**. A static `--header "Authorization: Bearer ..."` suits long-lived tokens only. For short-lived SSO or Kerberos credentials, set `headersHelper` on the server entry: a shell command that prints a JSON object of string headers, given 10 seconds, run at session start and on every reconnect without caching, overriding static headers of the same name. If a tool call gets 401 or 403, Claude Code re-runs it and retries once. Because the helper supplies `Authorization`, Claude Code never falls back to OAuth. For a project `.mcp.json` or local-scope server it runs only after you trust the folder, and a repository-supplied helper gets no credential variables from your environment.
code
json · 9 lines{
"mcpServers": {
"internal-kb": {
"type": "http",
"url": "https://mcp.internal.example.com/mcp",
"headersHelper": "/opt/bin/mcp-sso-headers.sh"
}
}
}go deeper
Know that /mcp is where you sign in to a remote server that needs a browser login.
Explain the three options — OAuth through /mcp or claude mcp login, static headers, headersHelper — and which kind of credential each fits.
Describe the helper's contract: JSON on stdout, 10-second limit, run per connection, retry after 401 or 403, no OAuth fallback, trust gating and the stripped credential variables.
Choose an authentication pattern a team can share without anyone committing a secret, weighing OAuth support against SSO integration through a common helper script.
## Three ways a remote server can authenticate Many remote MCP servers need credentials. Claude Code offers three mechanisms, and the right one depends on how the server issues them. The OAuth protocol details — discovery, PKCE, token audiences — belong to the MCP authorization material; this answer is about what you configure in Claude Code. | Mechanism | Suits | Where the credential lives | Who refreshes it | |---|---|---|---| | OAuth via `/mcp` | Servers that support OAuth | Claude Code's secure storage | Claude Code, automatically | | Static `--header` / `headers` | Long-lived API tokens | The configuration entry | You, by editing the entry | | `headersHelper` | SSO, Kerberos, short-lived tokens | Your own script or credential store | Your script, on each connection | ## OAuth sign-in through `/mcp` 1. Add the server: `claude mcp add --transport http tracker https://tracker.example.com/mcp`. 2. In a session, run `/mcp`, choose the server and follow the browser login. From the shell, `claude mcp login tracker` does the same; `--no-browser` prints the URL for SSH sessions so you paste the redirect back. 3. Claude Code stores the tokens securely and refreshes them. On a `401` it refreshes, reconnects and retries once before flagging the server. The `/mcp` menu offers **Clear authentication** to revoke and **Re-authenticate** when a refresh token is rejected. OAuth applies to HTTP and SSE servers; a WebSocket server authenticates with headers only. Non-interactive runs (`claude -p`, the SDK) cannot run the browser flow, so sign in interactively first. ## Static headers `--header "Authorization: Bearer <token>"` (or `headers` in JSON) works for a token that rarely changes. If the server rejects that header, Claude Code reports a **failed connection** rather than offering OAuth, because the credential to fix is the one you configured. ## `headersHelper` for short-lived credentials `headersHelper` names a command that generates headers at connection time. Its contract: - It must write a **JSON object of string key-value pairs** to stdout. - Claude Code runs it in a shell and gives up after **10 seconds**. - It runs **fresh on each connection** — at session start and on reconnect — and the result is not cached, so token reuse is your script's job. - Its headers **override static `headers`** with the same name. - If a tool call returns `401` or `403`, Claude Code re-runs the helper, reconnects and retries the call once; only if that fails is the server marked as needing authentication. - When it supplies `Authorization`, Claude Code does not fall back to OAuth; a rejection while connecting is a failed connection — fix the helper, then reconnect from `/mcp` to re-run it. Claude Code sets `CLAUDE_CODE_MCP_SERVER_NAME` and `CLAUDE_CODE_MCP_SERVER_URL` for the helper, so one script can serve several servers. ### Where it runs and what it can read - **Working directory** depends on where the server is configured: the project directory for a project `.mcp.json` or local-scope server, your configuration directory (`~/.claude` by default) for user scope. Give the script an **absolute path** or put it on `PATH`. - **Trust**: for a project `.mcp.json` or local-scope server, the helper runs only after you accept the trust dialog for that folder; until then the server connects with its static `headers` alone, and `claude -p` prints a `headersHelper not run` line. - **Environment**: a helper supplied by a repository or plugin runs without credential-like variables from your environment (names containing `TOKEN`, `SECRET`, `KEY`, `AUTH` and similar), so it should read its credential from a file or credential store. User- and local-scope helpers keep them. ## Choosing - The server speaks OAuth: use `/mcp`; nothing secret enters any file. - A long-lived token, private to you: `--header` at local or user scope. - Tokens that expire within hours, or an internal SSO: `headersHelper`. ## Common mistakes - Pasting a short-lived token into `headers` and re-adding the server every morning. - Using a relative script path and finding the helper not found from another directory. - Expecting the helper's output to be cached between connections. - Expecting `/mcp` to offer an OAuth sign-in to a server whose `Authorization` comes from a helper.
- Your helper's token expires mid-session and a tool call returns 401. What does Claude Code do?It re-runs the helper, reconnects with the fresh headers and retries the call once. Only if that retry also fails does it mark the server as needing authentication, with a message saying the server rejected the credential from its `headersHelper`; fix the helper and reconnect from `/mcp`.
- A teammate's `headersHelper` from the committed `.mcp.json` never runs on a fresh clone. Why?A helper is an arbitrary shell command, so for a project `.mcp.json` server Claude Code runs it only after the trust dialog for that folder is accepted; until then the server connects with static `headers` only. In `claude -p` it prints a `headersHelper not run` line explaining how to grant trust.
- headersHelper output is cached until the token expires
- /mcp can sign in to any remote server, including WebSocket ones
- A rejected static Authorization header falls back to OAuth
- A repository's helper inherits all your environment's tokens
- A relative headersHelper path always resolves against where you launched Claude Code