Claude Code MCP Scopes Explained: Local, Project and User (2026)

Claude Code stores each MCP server at one of three scopes. Local (the default) is private to you and one project. Project lives in a .mcp.json file in the repository, so the whole team shares it. User is private to you but available in every project on your machine.

If the same server name exists in more than one place, Claude Code uses only the highest-ranked definition: local, then project, then user, then plugins, then claude.ai connectors. This guide explains each scope, the approval rules for shared files and the settings admins use to control it all.

Checked against: Claude Code's MCP documentation and managed MCP documentation on 2 November 2026.

The three scopes at a glance

This table follows Anthropic's MCP docs. Set the scope with --scope (or -s) when you run claude mcp add. Our claude mcp add guide covers the rest of the command.

Local scope: private, one project

Anthropic's docs say: "Local scope is the default. A local-scoped server loads only in the project where you added it and stays private to you." Claude Code stores it "in ~/.claude.json under that project's path, so the same server won't appear in your other projects."

Use it for experiments, personal tokens and servers you are not ready to share.

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

Project scope: shared through git

Project scope writes to .mcp.json at the repository root. Commit the file and every teammate who clones the repo gets the same server list.

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

The resulting file looks like this:

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

Keep secrets out with variables

.mcp.json supports environment variable expansion in command, args, env, url and headers. The docs list two forms: ${VAR} and ${VAR:-default}. For example:

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

Two behaviors worth knowing. If a variable is unset and has no default, the config still loads with a warning and the literal ${VAR} text. And for remote servers, the docs say credential variables such as ANTHROPIC_API_KEY "read as empty" in url and headers, so a shared file cannot quietly send your Anthropic key to a third party. Both examples were checked against the docs on 2 November 2026.

Approvals for project servers

The docs say Claude Code "prompts for approval in interactive sessions before using project-scoped servers from .mcp.json files." To reset those choices, run claude mcp reset-project-choices.

A cloned repository also cannot pre-approve itself. Settings like enableAllProjectMcpServers inside the repo's own .claude/settings.json are ignored in an untrusted folder, and the server stays at "Pending approval."

One exception matters for automation. In claude -p runs, Agent SDK sessions and some cloud sessions, the docs say Claude Code "loads project-scoped servers without asking." Use disabledMcpjsonServers or --strict-mcp-config to keep a server out of those runs.

User scope: yours, everywhere

The docs describe user-scoped servers as "available across all projects on your machine while remaining private to your user account." They suit personal tools such as a docs lookup or a notes app.

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Which definition wins

When one name exists in several places, Claude Code "connects to it once, using the definition from the highest-precedence source." The order:

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

The entire entry comes from the winning source. If your local copy points at a test URL and the project copy points at production, you get the test URL with none of the project's headers.

claude mcp list and /mcp warn when the same name has different endpoints in different scopes. Remove the copy you do not want with claude mcp remove <name> --scope <scope>.

Where admins fit in

By default, the managed MCP docs say "anyone running Claude Code can connect any MCP server they choose." Admins can change that:

• managed-mcp.json deploys a fixed set of servers.
• managedMcpServers provides organization servers; the MCP docs say these rank above every scope from Claude Code v2.1.259.
• allowedMcpServers and deniedMcpServers filter what users can add.

Our Claude Desktop vs Claude Code comparison and the MCP permission review playbook show how teams combine these.

Other tools read .mcp.json too

A committed .mcp.json is not only for Claude Code. Devin's configuration import docs say Devin CLI imports MCP servers from .mcp.json and ~/.claude.json, among other Claude Code files. So a server you add at project scope may show up for teammates using other agents. Review the file in pull requests with that in mind.

Which scope should you use?

• A server the repo depends on (its database, its issue tracker): project.
• A personal token or a trial server: local.
• A tool you use in every project: user.
• A tool everyone in the company must have, or must not have: ask your admin for managed settings.

Next step

Draft a short approved-server list before your team starts committing .mcp.json files. Our tool permission planner helps decide which tools are read-only. For help setting up managed settings across a team, see Claude Code consulting.

Frequently asked questions