Scopes and Where Configuration Lives

Three scopes, one question: who needs this server?

Every MCP server you add lives in exactly one configuration scope. That scope controls whether the server is visible only to you in the current project, shared with your whole team, or available to you across every project on your machine. Choosing the wrong scope is a common source of confusion — a server you added in one project appears nowhere else, or a server you wanted to keep private ends up in the repository.

Three scopes, two configuration files

Claude Code organizes MCP servers across three scopes, stored in two files:

Add a server at a specific scope with the --scope flag:

claude mcp add --transport http stripe --scope project https://mcp.stripe.com

Omitting --scope defaults to local. Note that "local scope" for MCP uses ~/.claude.json (your home directory), while general local settings use .claude/settings.local.json (the project directory) — they are different files serving different purposes.

Scope precedence and deduplication

When the same server name is defined in more than one scope, Claude Code connects to it once, using the definition from the highest-precedence source. The order is: local > project > user > plugin-provided servers > claude.ai connectors. The entire entry from the winning source is used — fields are not merged across scopes.

This precedence lets you override a team server with your own local version without touching the shared configuration. Add a local-scope entry with the same name and Claude Code uses your version in that project while your teammates use the shared one.

Project scope and workspace trust

Project-scoped servers from .mcp.json need your approval before Claude Code connects them. This exists because a repository you clone could define servers that run arbitrary processes on your machine — the trust dialog is the gate. The first time you start Claude Code in a project with .mcp.json, Claude Code shows a prompt listing the pending servers. Approve them, and they connect. Reject them, and they stay at "Pending approval" in claude mcp list.

Approvals from your user settings (~/.claude/settings.json), managed settings, --settings, and .claude/settings.local.json apply in untrusted folders. Approvals from the project's .claude/settings.json do not — a cloned repository cannot pre-approve its own servers. To reset approval choices and re-evaluate, run claude mcp reset-project-choices.

How claude.ai connectors fit in — and when they vanish

If you authenticate Claude Code with a claude.ai subscription, MCP servers you have added at claude.ai/customize/connectors load automatically in every session. They appear in /mcp below your manually configured servers with a claude.ai indicator.

Here is the critical catch: connectors only load when your active authentication method is your claude.ai subscription. If you are using ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, or a third-party provider like Amazon Bedrock or Google Cloud's Agent Platform, connectors are silently absent — even if you previously ran /login. Run /status inside a session to confirm which authentication method is active. If connectors are missing, that is the first place to check.

A locally configured server takes precedence over a claude.ai connector pointing at the same URL. When this happens, /mcp lists the connector as hidden and shows you how to remove the duplicate if you prefer the connector version.

Disabling connectors: any-source-true semantics

The disableClaudeAiConnectors setting uses any-source-true semantics: if any settings source sets it to true, connectors are disabled — regardless of what other sources say. A project-level false cannot re-enable connectors that a user- or policy-level true has disabled. This is the opposite of the usual override direction. Use it intentionally:

• A project that should never load cloud connectors can set it to true in .claude/settings.json — and that wins for everyone who opens that project, even if their user settings leave it unset.
• A policy-level true blocks connectors for the entire organization regardless of what projects or users configure.

For a per-session alternative without touching settings files, set the environment variable before launching:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Environment variable expansion in .mcp.json

Project-scope .mcp.json files are committed to version control, which means they should not contain API keys, tokens, or machine-specific paths. Claude Code solves this with environment variable expansion. Two forms are supported:

• ${VAR} — expands to the value of VAR; fails to parse if VAR is unset
• ${VAR:-default} — expands to VAR if set, otherwise uses the default

Expansion works in the command, args, env, url, and headers fields. A typical pattern keeps the server URL in the file and reads per-user credentials from the environment:

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

Each developer sets their own API_KEY in their shell profile. The shared .mcp.json contains no secrets.