MCP Authentication

Some MCP servers need you to sign in. Claude Code supports OAuth, a script that makes headers, and managed sign-in for enterprises. For example, /mcp opens a panel where you start the OAuth sign-in for a server. This page describes the options only. It does not walk through any account sign-in.

OAuth works for http and sse servers. Headers work for http, sse, and ws servers. Use the server oauth fields, headers, headersHelper, and env vars to change it. Turn it off with claude mcp logout, Clear authentication in /mcp, disableClaudeAiConnectors, or ENABLE_CLAUDEAI_MCP_SERVERS. Tokens are in secure storage.

OAuth Options

Source: Connect Claude Code to Tools via MCP, Environment Variables, and the program for the rows marked

Undocumented: Only the program shows this item. It can change without notice.

Gated: Works only behind a flag or a server gate.

Item	Status	What It Does	How It Works
OAuth flow	Documented: An official docs page names this item.	Signs in to a remote server.	A `401` or `403` marks a server as needing auth. `/mcp` or `claude mcp login` runs the flow. A `401` on a signed-in server refreshes the token and retries once.
`oauth.clientId`	Documented: An official docs page names this item.	Gives a pre-configured client ID.	For servers with no dynamic client registration. Claude Code also finds a Client ID Metadata Document (CIMD) on its own.
`oauth.callbackPort`	Documented: An official docs page names this item.	Fixes the callback port.	The redirect URI is `http://localhost:PORT/callback`. A positive integer.
`oauth.authServerMetadataUrl`	Documented: An official docs page names this item.	Skips the discovery chain.	Must start with `https://`. The default order is RFC 9728 `/.well-known/oauth-protected-resource`, then RFC 8414 `/.well-known/oauth-authorization-server`.
`oauth.scopes`	Documented: An official docs page names this item.	Pins the requested scopes.	One space-separated string, at least one character. It overrides the scopes in metadata. Claude Code adds `offline_access` if the server advertises it.
`oauth.xaa`	Gated: Works only behind a flag or a server gate. CLAUDE_CODE_ENABLE_XAA=1	Enables XAA for the server.	Boolean. Without the gate Claude Code says `Remove 'oauth.xaa'`.
`--client-id`, `--client-secret`, `--callback-port`	Documented: An official docs page names this item.	Set the OAuth fields when you add a server.	See MCP Commands. You set the secret only at add time.
`MCP_CLIENT_SECRET`, `MCP_OAUTH_CALLBACK_PORT`	Documented: An official docs page names this item.	Env forms of the secret and port.	The secret skips the prompt. Login and `/mcp` never read it again.
`MCP_OAUTH_CLIENT_METADATA_URL`	Undocumented: Only the program shows this item. It can change without notice.	Overrides the CIMD URL.	The program logs `Using CIMD URL from env`.
Token storage	Documented: An official docs page names this item.	Keeps tokens.	Claude Code stores tokens securely and refreshes them. The client secret is in the macOS keychain or a credentials file. `Clear authentication` in `/mcp` and `claude mcp logout` remove them.
v2 runtime checks	Documented: An official docs page names this item.	Hardens OAuth.	Fails on an unexpected issuer. Sends credentials only to `https` or loopback token endpoints.
Local OAuth refusal	Documented: An official docs page names this item.	Handles hosted connectors.	Microsoft 365, Gmail, and Google Calendar hosts need claude.ai. Claude Code shows `is Anthropic-hosted and doesn't support local OAuth`.
No OAuth fallback	Documented: An official docs page names this item.	Respects your header.	If the server rejects a configured `Authorization` header (static or from a helper), the connection fails. There is no auth prompt.

`headersHelper`

A headersHelper is a shell command that prints request headers. Use it for short-lived tokens.

Item	Status	What It Does	How It Works
Command	Documented: An official docs page names this item.	Prints headers.	A shell command. The output is a JSON object of strings. It reaches its timeout after 10 s. It overrides static `headers`. It runs on each connect and again after a `401` or `403`.
`CLAUDE_CODE_MCP_SERVER_NAME`, `CLAUDE_CODE_MCP_SERVER_URL`	Documented: An official docs page names this item.	Tell the helper which server it serves.	Set only for the helper. The URL hides a live credential value as `REDACTED`.
`CLAUDE_PLUGIN_ROOT`	Documented: An official docs page names this item.	The plugin folder.	Set only for a plugin server.
Working folder	Documented: An official docs page names this item.	Resolves relative paths.	The plugin folder, the project folder, the primary working folder, or `~/.claude` (user, managed, connector). It depends on where you configure the server.
Env scrub	Documented: An official docs page names this item.	Hides credential variables.	Project `.mcp.json`, plugin, and project agent servers receive no variables with `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, or `AUTH` in the name, plus a fixed list.
Trust rule	Documented: An official docs page names this item.	Runs the helper late.	Project and local servers run it only after the trust dialog for the folder that declares them. Until then, Claude Code uses only static `headers`.
`${user_config.*}`	Documented: An official docs page names this item.	Plugin options.	Not allowed. Claude Code reports the server as misconfigured. Before `2.1.207` it substituted them.
Policy refusal	Documented: An official docs page names this item.	Refuses a plugin helper.	A marketplace entry with `headersHelper` must inline its full manifest with `strict: false`. Otherwise Claude Code refuses to run it.

XAA

XAA (SEP-990) signs you in through an enterprise identity provider (IdP). It is off. Set CLAUDE_CODE_ENABLE_XAA=1 to turn it on.

Item	Status	What It Does	How It Works
XAA	Gated: Works only behind a flag or a server gate. CLAUDE_CODE_ENABLE_XAA=1	Signs in through an enterprise IdP.	All XAA servers share one IdP connection. Claude Code swaps a cached IdP `id_token` for a server token. Servers with `oauth.xaa` use it.
Gate	Gated: Works only behind a flag or a server gate. CLAUDE_CODE_ENABLE_XAA=1	Turns XAA on.	An env var.
Setup	Gated: Works only behind a flag or a server gate. CLAUDE_CODE_ENABLE_XAA=1	Stores the IdP data.	`claude mcp xaa setup` writes `xaaIdp`. The secret comes from `MCP_XAA_IDP_CLIENT_SECRET` and goes to the keychain.
Login	Gated: Works only behind a flag or a server gate. CLAUDE_CODE_ENABLE_XAA=1	Caches the IdP token.	`claude mcp xaa login`. Without it Claude Code says `no IdP connection`.

Claude.ai Connectors

Connectors are MCP servers that you configure in claude.ai. Claude Code fetches them only when you use a claude.ai login.

Item	Status	What It Does	How It Works
Fetch	Documented: An official docs page names this item.	Loads the connectors of your account.	Only with a claude.ai subscription login. Not with an API key, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper`, a cloud provider, a profile, or a `setup-token` token. Works in the terminal, VS Code, JetBrains, and the SDK.
`ENABLE_CLAUDEAI_MCP_SERVERS`	Documented: An official docs page names this item.	Switch for the fetch.	`false` stops it for the shell session.
`disableClaudeAiConnectors`	Documented: An official docs page names this item.	Switch in settings.	See MCP Settings and Policy.
Per-tool controls	Documented: An official docs page names this item.	Organization policy on connector tools.	`ask` prompts on each call. `blocked` hides the tool. See `toolPermissions` in Server Configuration.
Session token rejected	Documented: An official docs page names this item.	A separate state from a connector problem.	Run `/login`, then reconnect. Authorizing the connector again does not help.
Cloud and desktop sessions	Documented: An official docs page names this item.	Other delivery paths.	A cloud host or the desktop app delivers connectors. `disableClaudeAiConnectors` does not act on them.

Example

.mcp.json: OAuth with a fixed port, and a header helper
{
  "mcpServers": {
    "crm": {
      "type": "http",
      "url": "https://crm.example.com/mcp",
      "oauth": {
        "clientId": "my-client-id",
        "callbackPort": 8765,
        "scopes": "read write"
      }
    },
    "internal": {
      "type": "http",
      "url": "https://tools.example.com/mcp",
      "headersHelper": "./scripts/mcp-headers.sh"
    }
  }
}

The helper script prints {"Authorization": "Bearer <token>"} to stdout. Then it exits.

How It Works

Errors

Each row is a family of messages. The backticked text is the start that every message in the family shares.

Start of Message	Status	What It Means	Cases
`XAA`, `authServerMetadataUrl must`, `Configured auth server metadata`, `HTTP ${…} fetching configured auth server`, `Unexpected auth result`, `Invalid authorization URL`, `No TTY available to prompt for client secret`, `Enter OAuth client secret`, `Unable to build claude.ai connector auth URL`, `Server type "${…}" does not support OAuth`, `No OAuth flow in progress`, `Invalid callback URL`, `MCP OAuth failed`, `OAuth flow completed without`, `No available ports for OAuth redirect`, `clientMetadataUrl must`	Undocumented: Only the program shows this item. It can change without notice.	An MCP OAuth or XAA (cross-app access) sign-in step failed.	Discovery of protected resource metadata or authorization server metadata failed or did not match, the token endpoint is not HTTPS, the token exchange or jwt-bearer grant failed or returned an unexpected shape, XAA is not enabled (`CLAUDE_CODE_ENABLE_XAA=1`), no IdP connection is configured, or the callback URL does not belong to this sign-in. In `2.1.311`, the server now names an authorization server other than the one you signed in with (`XAA: authorization server changed`). If the move is expected, run `claude mcp remove` for the server and add it again with its client secret (`chunk-ejpywc4g.js:350`).

MCP
MCP Commands
MCP Env Vars
Settings: Authentication for the sign-in of Claude Code itself

OAuth Options​

headersHelper​

XAA​

Claude.ai Connectors​

Example​

How It Works​

Errors​

Related Pages​