​

What you can do with MCP

• Implement features from issue trackers: “Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub.”
• Analyze monitoring data: “Check Sentry and Statsig to check the usage of the feature described in ENG-4521.”
• Query databases: “Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database.”
• Integrate designs: “Update our standard email template based on the new Figma designs that were posted in Slack”
• Automate workflows: “Create Gmail drafts inviting these 10 users to a feedback session about the new feature.”
• React to external events: an MCP server can also act as a channel that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you’re away.

​

Find and build MCP servers

/plugin install mcp-server-dev@claude-plugins-official

/mcp-server-dev:build-mcp-server

​

Installing MCP servers

​

Option 1: Add a remote HTTP server

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

​

Option 2: Add a remote SSE server

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

​

Option 3: Add a local stdio server

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

​

How Claude Code stops a stdio server

• On macOS and Linux: Claude Code sends SIGINT, then SIGTERM if the process is still running 100 milliseconds later, then SIGKILL after a further 400 milliseconds.
• On Windows: Claude Code closes the server’s stdin, then ends the server’s process tree if the process is still running 300 milliseconds later.

​

Option 4: Add a remote WebSocket server

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

​

Add a server from setup instructions written for another client

• A URL such as https://mcp.example.com/mcp: the server is remote.
• A launch command such as npx -y @example/mcp-server: the server runs on your machine.
• An mcpServers JSON block: configuration written for another client’s settings file.

​

Add a server from a URL

claude mcp add --transport http example https://mcp.example.com/mcp

​

Add a server from an npx, uvx, or binary command

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

​

Add a server from an mcpServers JSON block

• A url with no type: add "type": "http", "type": "sse", or "type": "ws" to match the endpoint. Claude Code reads an entry with no type as a stdio server, so a url entry without a type fails.
• A key with characters other than letters, numbers, hyphens, and underscores: pick a server name that uses only those characters. Otherwise the key is the server name.

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

​

Managing your servers

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

​

Server status

• ⏸ Pending approval (run `claude` to approve): a project-scoped server from .mcp.json that you haven’t approved yet. Claude Code shows it in both claude mcp list and claude mcp get <name>. Run claude interactively to review and approve it.
• ✘ Rejected (see disabledMcpjsonServers in settings): a .mcp.json server that a disabledMcpjsonServers entry rejects. Claude Code shows it only in claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): a server that the project’s disabledMcpServers list names. Claude Code shows it in both claude mcp list and claude mcp get <name>. Turn the server back on from the /mcp panel.
• ✘ Blocked by enterprise managed policy: a server that one of your organization’s policies refuses. Claude Code shows it in both claude mcp list and claude mcp get <name>. A server blocked by an allowlist, a denylist, or another restriction in managed MCP configuration is hidden from both commands rather than shown with this status. Ask your administrator which policy blocks the server.

​

Project server approvals and workspace trust

• your user ~/.claude/settings.json
• managed settings
• settings passed with --settings

​

Server status detail

Connection failures and unconfigured servers

• The path and query never appear in that message.
• For a server in the local, project, or user scope or in managed MCP configuration, the origin shows the host as written in that configuration, so a ${VAR} reference in the host isn’t expanded in the message.
• For a failure with no status or error code, Claude Code shows the error text without the origin.

​

Configuration warnings

• Hidden whitespace: Claude Code warns when an MCP config value carries hidden leading or trailing whitespace, which often comes from pasting a token with a trailing newline. Claude Code checks command, url, each args entry, and the values and key names under env and headers. Claude Code shows the warning in claude mcp list output and in /mcp, naming the affected fields without echoing their values, for example Leading or trailing whitespace in: headers.Authorization. Claude Code doesn’t trim the whitespace and uses the values exactly as written, so edit the configuration to remove it.
• Same name in more than one scope: if you define the same server name in more than one scope with different endpoints, Claude Code warns about the conflict in claude mcp list output and in /mcp. Claude Code stores OAuth sign-ins per endpoint, so when you authenticate the definition that loads in one project, you still need to sign in separately in a project where a different definition loads. Keep the endpoint you want and remove the others with claude mcp remove <name> --scope <scope>. In the warning, Claude Code quotes each scope’s endpoint as written in your configuration, with ${VAR} references unexpanded, so it never shows a resolved value such as an API key.
• Reserved names: Claude Code reserves the names of its built-in servers, including workspace, claude-in-chrome, computer-use, Claude Preview, and Claude Browser. If your configuration defines a server with a reserved name, Claude Code skips it at load time and shows a warning asking you to rename it. claude mcp add rejects a reserved name with an error. Claude Preview and Claude Browser both name the built-in server that the Claude Code desktop app’s preview pane uses.
• Missing environment variable: if a ${VAR} reference in a server’s configuration names a variable that isn’t set and has no :-default, Claude Code warns in claude mcp list output and in /mcp, naming the variable, and still loads the server with the ${VAR} text unexpanded. Set the variable or add a ${VAR:-default} fallback. In a remote server’s url and headers, some credential variables read as empty instead, with no warning.

​

Tool availability

• With tool search, the default: the wait happens inside the ToolSearch call.
• Without tool search: Claude uses the WaitForMcpServers tool instead. Configurations without tool search include ENABLE_TOOL_SEARCH=false and a model earlier than Claude Opus 4.5, Claude Sonnet 4.5, and Claude Haiku 4.5 on Google Cloud’s Agent Platform. For an ANTHROPIC_BASE_URL gateway, see Tool search through an LLM gateway.
• On a Microsoft Foundry deployment hosted on Azure: Claude starts on the tool-search path rather than with WaitForMcpServers, since Claude Code discovers the deployment’s server-side rejection only from the API. After Claude Code switches that deployment to upfront loading, tools from a server that finishes connecting become available on Claude’s next request.

​

Disable a server without removing it

• disabledMcpServers: an opt-out list for user-configured servers, plugin servers, servers your organization provides through managed settings, the claude.ai connectors Claude Code fetches itself, and built-in servers that default to on. Claude Code doesn’t connect to a server you list here. When you disable a claude.ai connector with the per-project /mcp toggle described in Disable claude.ai connectors, Claude Code writes it to this list under its display name, for example claude.ai Slack.
• enabledMcpServers: an opt-in list for built-in servers that default to off, such as computer-use. Claude Code connects to a default-off server only when you list it here.

​

MCP client runtimes

• Sessions on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry, unless a host platform that embeds Claude Code sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Sessions signed in through a Claude apps gateway
• Sessions where you turn off telemetry or feature-flag fetching, for example with DISABLE_TELEMETRY

• Asks HTTP, stdio, and claude.ai connector servers whether they support the newer revision and uses it with those that do. That includes the connectors of cloud and Remote Control sessions. Claude Code connects to every other server as v1 does.
• Receives list_changed notifications from servers on the newer revision over a stream it holds open.
• Doesn’t register a channel server that connects on the newer revision, because that revision can’t carry channel messages.
• Fails an MCP OAuth sign-in whose authorization response names an unexpected issuer.
• Sends MCP OAuth credentials only to a token endpoint served over HTTPS or at localhost, 127.0.0.1, or ::1. Sign-in fails for a server whose token endpoint is plain http:// anywhere else, such as a device on your local network. See Refusing to send credentials to non-https token endpoint.

​

Dynamic tool updates

• In an interactive terminal session, Claude Code fetches the updated list from that server, so you don’t need to reconnect it.
• In non-interactive mode with the -p flag and in the Agent SDK, Claude Code refreshes only the tool list on these notifications.

​

Notification streams on the v2 runtime

• The stream closes again within 10 seconds: Claude Code reopens it up to three times, then stops for that connection.
• The stream stays open longer than 10 seconds, then closes, as streams to serverless hosts commonly do: after five reopens in an hour, Claude Code waits about six hours before the next one.

​

Automatic reconnection

​

Mid-session drops of a remote server

• In an interactive session: /mcp shows the server as pending while Claude Code reconnects. After five failed attempts, Claude Code marks the server as failed, or as needing authentication when the server needs authorizing again. When it marks the server as failed, you see an MCP server "<name>" disconnected · open /mcp to reconnect notification. You can retry manually from /mcp.
• In claude -p runs and Agent SDK sessions: Claude Code makes the same five attempts, with no /mcp panel to show them. If all five fail, the run continues without the server’s tools:
  • After a transient error, such as a 5xx response or a timeout: Claude Code keeps retrying an HTTP or SSE server in the background. Retries last up to about half an hour, and the server’s tools become available again when one connects. Until then, an Agent SDK session reports the status failed, and your code can reconnect the server. To reconnect it in claude -p, start the run again.
  • When the server needs you to sign in again: Claude Code stops retrying, and an Agent SDK session reports the server’s status as needs-auth. Sign in with claude mcp login <name> in your shell. Then start the run again or, in an Agent SDK session, reconnect the server instead.

​

Failed first connections

• A stdio server’s first connection. To try it again, see Stdio servers that exit or fail to start
• A WebSocket server’s first connection. To try it again in an interactive terminal session, select Reconnect from the server’s menu in /mcp
• An authentication or not-found error, because it requires a configuration change to resolve. When a headersHelper is the server’s only source of the Authorization header, Claude Code retries an authentication error anyway, because it re-runs the helper on each attempt and can pick up a fresh credential

​

Stdio servers that exit or fail to start

​

Failed discovery requests

​

Retry failed servers yourself

​

How Claude learns that a server failed

• With tool search, Claude Code tells Claude which server failed and its connection error, so Claude reports the connection failure in its response. Claude Code includes the same information in ToolSearch results that find no matching tool.
• In any configuration without tool search, Claude Code doesn’t report failed server connections to Claude.

​

Push messages with channels

​

Time limits on MCP tool calls

• Per server: add a timeout field in milliseconds to that server’s configuration entry
• Across servers: set MCP_TOOL_TIMEOUT

​

Automatic backgrounding of long tool calls

• Set the CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS environment variable in milliseconds to change the threshold, or set it to 0 to turn automatic backgrounding off. With 0, Claude also waits for MCP tasks in an interactive session
• Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS to 1 to turn off automatic backgrounding and background commands

• Calls from subagents; Claude Code backgrounds only main-conversation calls
• Calls to IDE servers
• Calls in non-interactive mode, unless CLAUDE_AUTO_BACKGROUND_TASKS is set to 1, since a one-shot run can end before the result arrives

​

MCP tasks that run on the server

​

Stop an MCP task or get its result

MCP task <server task id> (<server>/<tool>) completed.

​

Answer a question from an MCP task

​

Exit, clear, or resume while an MCP task runs

​

What a call needs to become an MCP task

• The server supports tasks
• The server is an HTTP, stdio, or claude.ai connector server connected on protocol revision 2026-07-28. Setting MCP_SDK_GENERATION=v1 or MCP_PROTOCOL_NEGOTIATION=legacy rules that out
• The session fetches feature flags, so not on a third-party provider such as Amazon Bedrock, and not with telemetry or flag fetching turned off
• Anthropic has turned MCP tasks on for your kind of session. On v2.1.304 or later that covers terminal CLI sessions, Agent SDK sessions, and GitHub Actions runs. Other surfaces, such as the VS Code extension and the desktop app, don’t have MCP tasks
• The call comes from the main conversation, not from a subagent
• Either the session is interactive, or an Agent SDK session or a claude -p run reading --input-format stream-json has:
  • CLAUDE_AUTO_BACKGROUND_TASKS at 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND not 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS not 0

​

Status messages on an MCP task

​

Time limits on MCP tasks

​

Make Claude wait for the result of an MCP task

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS set to 0: Claude waits for every MCP tool call until the call ends
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND set to 1: Claude waits for a task’s result. While automatic backgrounding is on, it moves the call after two minutes by default, so short tasks finish in place and long ones don’t block you. The moved call is a plain background call rather than an MCP task. It doesn’t survive exiting the session

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

​

MCP tasks for server authors

​

Answer the call with a task

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

​

Report status, results, and questions

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

​

Plugin-provided MCP servers

• Plugins define MCP servers in .mcp.json at the plugin root or inline in plugin.json
• When you enable a plugin, Claude Code starts its MCP servers automatically
• Claude Code offers plugin MCP tools alongside manually configured MCP tools
• You add and remove plugin servers by installing or uninstalling the plugin, not with /mcp commands. You can still toggle an installed plugin server off in /mcp, which stops Claude Code from connecting to it without removing the plugin

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

• Automatic lifecycle: servers connect and disconnect at these points:
  • At session startup, Claude Code connects the servers for enabled plugins automatically. In /mcp, a remote (HTTP or SSE) plugin server you’ve used before can show the cached status instead; Claude Code connects it when Claude first calls one of its tools. When a stdio plugin server’s connection failed less than 15 minutes earlier, Claude Code skips the connection
  • If you enable or disable a plugin during a session, Claude Code connects or disconnects its MCP servers when the change applies. Apply plugin changes without restarting describes when that is. In a session without an interactive terminal, /reload-plugins doesn’t connect or disconnect plugin MCP servers; those changes take effect in your next session
  • When you reload, Claude Code keeps the live connections of plugin servers whose configuration is unchanged, and does the same when you replace the session’s MCP server list from the Agent SDK without naming them
  • When you move the session with /cd on v2.1.246 or later, Claude Code connects the servers of plugins the new directory’s settings enable and disconnects the servers of plugins that are no longer enabled, so you don’t need to run /reload-plugins after the move
  • In cloud sessions, an MCP call to a plugin server that isn’t connected yet, such as right after an idle session wakes, starts the server on demand and waits for it to connect
• Path placeholders: ${CLAUDE_PLUGIN_ROOT} resolves to the plugin’s installation directory, ${CLAUDE_PLUGIN_DATA} to its persistent state directory, and ${CLAUDE_PROJECT_DIR} to the stable project root. Substitution applies to:
  • stdio servers: command, args, env
  • http, sse, and ws servers: url, headers, and headersHelper
• User environment access: access to the same environment variables as manually configured servers
• Multiple transport types: support for stdio, SSE, HTTP, and WebSocket transports, though transport support may vary by server

• stdio server: it prints Command: stdio, an empty Args: line, and each environment variable as NAME=[REDACTED]
• WebSocket server: it prints URL: ws and each header as <name>: [REDACTED], and claude mcp list shows ws in place of the URL

mcp__plugin_my-plugin_database-tools__query

​

MCP installation scopes

​

Local scope

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

​

Project scope

# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

• Add it to disabledMcpjsonServers, which blocks it in every permission mode.
• Exclude project settings entirely with --setting-sources or the SDK’s settingSources option.
• Start the session with --strict-mcp-config. Claude Code then uses only the MCP servers you pass with --mcp-config. Skipping the approval prompt for the project-scoped servers Claude Code isn’t loading requires Claude Code v2.1.246 or later; before v2.1.246, a strict session still waited on approval for them, which left background sessions waiting at startup. See Exclusive control with managed-mcp.json for what the flag does under a managed MCP file.

​

User scope

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

​

Scope hierarchy and precedence

1. Local scope
2. Project scope
3. User scope
4. Plugin-provided servers
5. claude.ai connectors

​

Environment variable expansion in .mcp.json

• ${VAR}: expands to the value of environment variable VAR
• ${VAR:-default}: expands to the value of VAR if VAR is set, or to default if it is unset

​

Example with variable expansion

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

​

Unset variables without a default

​

Variables set to an empty string

​

Credential variables that read as empty

• Claude Code’s own credentials, such as ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN
• Your cloud provider’s credentials, such as AWS_BEARER_TOKEN_BEDROCK
• Other credentials your environment carries, such as HTTPS_PROXY and NPM_TOKEN

​

How references appear in /mcp and CLI output

• The URL or command line in a server’s /mcp detail view
• claude mcp list and claude mcp get output

​

Practical examples

​

Example: Connect to GitHub for code reviews

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

​

Example: Query your PostgreSQL database

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

​

Authenticate with remote MCP servers

• For a server you haven’t signed in to, either status code flags it in /mcp so you can complete the OAuth flow.
• For a claude.ai connector, a 401 caused by claude.ai rejecting your session token doesn’t flag the connector, because re-authorizing the connector can’t fix your login. Claude Code shows the session-token-rejected state instead.
• For a server whose Authorization header you configured, in headers or through a headersHelper, a 401 or 403 while connecting doesn’t flag the server, because the credential to fix is the one you configured. Claude Code reports the connection as failed instead. If you set that header from a ${VAR} reference, check whether that variable is one Claude Code reads as empty.
• For a connector delivered to a cloud session, Claude Code doesn’t run a sign-in flow, because the session’s proxy authenticates to the connector with the authorization you granted in claude.ai. When a connector there needs authorizing again, reconnect it at claude.ai/customize/connectors rather than from the session.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

​

Authenticate from the command line

claude mcp login sentry

claude mcp login sentry --no-browser

​

Use a fixed OAuth callback port

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

Use pre-configured OAuth credentials

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

Override OAuth metadata discovery

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

​

Restrict OAuth scopes

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

​

Use OAuth with a server behind an authenticating proxy

• The proxy’s header: pass it with --header, the headers field, or a headersHelper, under the name the proxy reads
• The OAuth sign-in: keep Authorization out of the configured headers, then sign in with claude mcp login <name> in your shell. If you configure an Authorization header, Claude Code uses it as the server’s credential and doesn’t fall back to OAuth for that server.

​

Use dynamic headers for custom authentication

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

• The command must write a JSON object of string key-value pairs to stdout
• Claude Code runs the command in a shell and gives up on it after 10 seconds
• Claude Code picks the command’s working directory by where you configured the server, so give the script as an absolute path or put it on PATH
• Dynamic headers override any static headers with the same name

​

Where the helper runs

​

Which variables a helper can read

• Removed: a server in a project .mcp.json or in a plugin, and an inline server in an agent file from your project or from an --add-dir directory
• Not removed: a server at user or local scope, in managed MCP, from a claude.ai connector, or supplied by the SDK or --mcp-config, and an inline server in an agent file from ~/.claude/agents/, from managed settings, or passed with --agents

​

Trust a folder before its headersHelper runs

• Trust that doesn’t count: a parent folder’s trust, and the automatic trust a claude -p or SDK session gets for hooks in settings files
• Until you trust the folder: Claude Code connects the server with its static headers alone. In a claude -p or SDK session it also prints one headersHelper not run line per server to stderr, telling you how to grant the trust.
• Trust without a dialog: set projects["<path>"].hasTrustDialogAccepted to true in ~/.claude.json. <path> is the folder Project allow rules and workspace trust says Claude Code keys the trust on.

​

Sign in to an MCP server behind a gateway that requires a header

• A server whose configuration you can edit: set it in headers or return it from a headersHelper
• A server that managed MCP or a plugin supplies: ask your administrator or the plugin’s author to add the header to the server’s entry

• The authorization page: you sign in on this page in your browser, which doesn’t send the configured headers. If your browser gets the gateway’s error instead of the page, ask whoever runs the gateway to let the page through without the header.
• An authorization server on another origin: if a gateway in front of that server requires the header too, sign-in fails there. Ask whoever runs that gateway to let OAuth requests through without the header.

​

Add MCP servers from JSON configuration

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

​

Import MCP servers from Claude Desktop

# Basic syntax
claude mcp add-from-claude-desktop

claude mcp list

​

Use MCP servers from claude.ai

/mcp

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper is active
• A third-party provider such as Amazon Bedrock or Google Cloud’s Agent Platform is active
• ANTHROPIC_PROFILE, the federation variables, or an active Anthropic profile supplies the credential
• CLAUDE_CODE_OAUTH_TOKEN holds a token from claude setup-token, which can only make model requests

1. Run /login to sign in again.
2. Reconnect the connector from /mcp.

​

How connectors reach Claude Code

• Cloud sessions: allowedMcpServers and deniedMcpServers entries that reach the session, for example through server-managed settings, filter the delivered connectors too. The session’s proxy rewrites each connector’s URL, so a serverUrl pattern written for the connector’s own URL doesn’t match it. To admit delivered connectors alongside a URL allowlist in a self-hosted environment, add the serverUrl entries listed under Connector traffic leaves your network. Claude Code drops the delivered connectors when a managed-mcp.json is present on the host that runs the session, such as a self-hosted runner host, whether or not you set allowAllClaudeAiMcps.
• Desktop app local and SSH sessions: the desktop app registers the connectors as in-process type: "sdk" servers, and no MCP setting or managed-mcp.json reaches them. A user keeps a connector out of their own sessions by disconnecting it at claude.ai/customize/connectors. An organization blocks a connector’s tools or turns off Claude Code in the desktop app entirely.

​

Organization controls on connector tools

• Tool set to ask: Claude Code prompts on every call with the reason Your organization requires approval for this tool. The prompt appears even in acceptEdits, auto, and bypassPermissions permission modes. In the terminal, the prompt has no option to remember your choice. Allow rules that match the tool don’t skip the prompt either. In dontAsk mode, which never prompts, Claude Code denies the call instead.
• Tool set to blocked: Claude Code filters the tool out before Claude sees it, so it never appears in Claude’s tool list. In sessions where Claude Code fetches connectors itself, the /mcp tool list still shows the tool, marked disabled by your organization.

​

Disable claude.ai connectors

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Use Claude Code as an MCP server

# Start Claude as a stdio MCP server
claude mcp serve

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

which claude

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

​

Read a background command’s output as an MCP client

• To read the output so far: open the file at that path from your client, or pass the path as file_path to the server’s Read tool
• To tell when the command has finished: append an echo of a fixed string to the command value, as in npm test; echo DONE. The command has finished once that string appears in the file. Without the string, nothing marks the end, because Claude Code adds no closing line to the file and doesn’t notify your client.
• To read the end of long output: Read with only file_path returns the first page, or fails when the file exceeds the size limit. Pass offset and limit as well, which works at any file size:
  1. Call Read with offset and limit both set to 1, and take totalLines from the result
  2. Call Read again with offset set to totalLines minus nine and limit set to 10
  3. Look for your echo string in the last ten lines, which the second call returns

​

MCP output limits and warnings

• Output warning threshold: Claude Code displays a warning when any MCP tool output exceeds 10,000 tokens
• Configurable limit: you can adjust the maximum allowed MCP output tokens using the MAX_MCP_OUTPUT_TOKENS environment variable
• Default limit: the default maximum is 25,000 tokens
• Scope: the environment variable applies to tools that don’t declare their own limit. Tools that set anthropic/maxResultSizeChars use that value instead for text content, regardless of what MAX_MCP_OUTPUT_TOKENS is set to. Tools that return image data are still subject to MAX_MCP_OUTPUT_TOKENS
• Over the limit: when a successful result with no image content exceeds the token limit, Claude Code saves it to a file and replaces it in the conversation with a message that names the file path, so Claude reads the file when it needs the content. The file goes in the session’s tool-results directory under ~/.claude/projects/.
• Response size from HTTP and SSE servers: when a response from an HTTP or SSE server passes 16 MiB, Claude Code stops reading it and the request fails. The limit applies after decompression to one JSON response body or one event of an event stream. If you maintain the server, return less data per response to stay under the limit, for example by paginating results
• Message size from WebSocket servers: when a WebSocket server sends one message over 16 MiB, Claude Code closes the connection, and calls in progress on that server fail. If you maintain the server, return less data per message to stay under the limit

• Character limit for text results: for a tool that doesn’t declare anthropic/maxResultSizeChars, Claude Code saves a successful result with no image content to a file once it’s longer than 50,000 characters, whatever its token count. Setting MAX_MCP_OUTPUT_TOKENS doesn’t change this threshold
• Error results: when a tool returns a result marked isError: true, Claude receives the result’s text as the tool’s error message. Error text longer than about 11,000 characters keeps only its first 5,000 and last 5,000 characters, with a marker between them that says how many characters were removed

export MAX_MCP_OUTPUT_TOKENS=50000
claude

​

Raise the limit for a specific tool

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

​

Images in tool results

​

Tool input schemas with a root-level combinator

• allOf: properties from every branch are merged, and each branch’s required list still applies
• anyOf and oneOf: properties from every branch are merged, and each branch’s required list is described in the tool description instead of enforced by the schema

​

Tools with invalid input schemas

• Top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, _, ., and -
• The schema must be valid against the JSON Schema draft 2020-12 meta-schema. Claude Code applies this check to schemas that declare no $schema and schemas that declare draft 2020-12. A schema that declares any other dialect skips this check, though the property-name check above still applies

• Claude gets the tool unchanged, and the server’s log records input schema would be rejected by the Anthropic API for it
• If the API then rejects the schema, see Tools whose input schema the API refuses

​

Tools whose input schema the API refuses

• If your session fails with a 400 error that names a tool by its position: follow the steps in Tool input schema is invalid
• If you use the server: you don’t need to do anything. Claude can still call the tool, but doesn’t see its parameters
• If you maintain the server: fix the tool’s input schema on the server. The log line ends with The API said: and the API’s reason for rejecting the schema. Validate the arguments the server receives, because Claude calls the tool without seeing its parameters

​

Tools with names longer than 128 characters

​

Require approval for a specific tool

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

​

Mark tools that are safe to call twice

• idempotentHint: the tool can change something, and calling it again with the same arguments is safe
• readOnlyHint: the tool changes nothing. Claude Code also runs the tool’s calls in parallel with other read-only calls.

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

​

Respond to MCP elicitation requests

• Form mode: Claude Code shows a dialog with form fields defined by the server (for example, a username and password prompt). Fill in the fields and submit.
• URL mode: Claude Code asks whether to open a link in your browser. Servers use this mode for a flow that finishes outside the terminal, such as sign-in.

​

Elicitation modes Claude Code declares

• Connections that use protocol revision 2026-07-28
• Connections on the earlier protocol revisions, 2025-11-25 and older, to the stdio, sse, http, and ws servers in a user’s Claude Code MCP configuration. Requires Claude Code v2.1.287 or later

​

Use MCP resources

​

Reference MCP resources

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Compare @postgres:schema://users with @docs:file://database/user-model

​

Scale with MCP tool search

​

Tool search for MCP server authors

• What category of tasks your tools handle
• When Claude should search for your tools
• Key capabilities your server provides

• Server instructions, and the description of a tool that loads upfront: 4,096 characters
• The description of a tool that Claude loads through tool search: 16,384 characters

​

Change the description length limits

​

Mark a tool to load upfront or stay deferred

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

​

Configure tool search

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later: tool search is on by default, the same as on the Anthropic API.
• Earlier Agent Platform models: Claude Code loads all MCP tools upfront, because their serving stacks reject the required beta header. ENABLE_TOOL_SEARCH=true doesn’t override this.

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

​

Tool search through an LLM gateway

​

Tools that stay deferred below the ENABLE_TOOL_SEARCH=auto threshold

​

Exempt a server from deferral

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

​

Defer a server’s tools

​

Use MCP prompts as commands

​

Execute MCP prompts

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

​

Managed MCP configuration