Egor Urvanov

MCP scopes in Claude CodeLocal, project and user — where a server lives and who sees it

The three MCP server scopes in Claude Code: local, project and user. Where the setup lives, who sees it, what wins when names collide, how to share servers with a team and keep secrets out of commits.

· 4 min · · Harness

An MCP server’s scope answers two questions: which projects it works in and who sees it. Claude Code has three scopes: local, project and user. Below: how they differ, which to pick, what wins when names collide and how to share servers with a team. What MCP is and how to connect it is in the MCP for an AI agent article.

Three scopes

Localyou · this projectProjectthe whole teamUseryou · all projects● model, people, systems, data  ● agent and harness
ScopeWorks inWho sees itStored in
Localcurrent projectonly you~/.claude.json
Projectcurrent projectthe whole team, via the repo.mcp.json in the root
Userall your projectsonly you~/.claude.json
Takeaway
In this exampleThe same server can be connected for yourself in one project, for the whole team, or for all your projects.
In generalLocal is the default: the server is visible only to you and only in this project.
What to doSee which scope each of your servers lives in: claude mcp list.

Which one to pick

Tell the agent

Show which scopes my MCP servers are configured in and suggest which ones to move to project for the team.

The agent runs the commands itself: claude mcp list and claude mcp get.

How to do it by handLocalpersonal and trial servers, servers with private keysProjectshared team toolsUserpersonal utilities for all projects● model, people, systems, data  ● agent and harness
# local — the default
claude mcp add --transport http stripe https://mcp.stripe.com
# project — the whole team, .mcp.json file
claude mcp add --transport http shared-server --scope project https://example.com/mcp
# user — all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Server list: claude mcp list; details: claude mcp get <name>; remove: claude mcp remove <name>; inside Claude Code: /mcp.

Takeaway
In this exampleAn experiment starts in local, a shared tool lives in project, a personal utility in user.
In generalThe scope decides who sees the server and where its configuration lives.
What to doAdd a shared tool with --scope project and a personal one with --scope user.

What wins when names collide

If a server with the same name exists in several places, the entry from the topmost layer is used whole.

Managed MCP (v2.1.259+)claude.ai connectorspluginsUserProjectLocalthe entry from the top layer is used whole, fields are not merged● model, people, systems, data  ● agent and harness
Takeaway
In this exampleLocal overrides project and user, project overrides user, and plugins, claude.ai connectors and managed MCP sit below.
In generalA personal entry overrides a shared one with the same name as a whole: fields of the two entries are not merged.
What to doGive personal servers different names so they do not override shared ones.

Project: shared setup for the team

.mcp.jsonThe file sits in the project root, in the repository: the whole team gets the same servers.
ApprovalIn an interactive session Claude Code asks before using servers from .mcp.json.
No promptIn non-interactive runs (claude -p, the Agent SDK, cloud sessions) servers load without a prompt.
Folder trustIn an untrusted folder the server waits for approval (“Pending approval”) until the trust dialog.
DisableAdd an unwanted server to disabledMcpjsonServers; claude mcp reset-project-choices clears approval choices.
Takeaway
In this exampleA file in the repository makes the agent setup shared: a new member gets the servers together with the code.
In generalApproval guards against a stranger’s server in interactive work, while in automated runs the server turns on at once.
What to doReview .mcp.json in code review like any code.

Secrets in .mcp.json

The file holds environment variable names. ${VAR} inserts the value and ${VAR:-default} sets a fallback. Expansion works in command, args, env, url and headers.

.mcp.jsonin the file${API_KEY}everyone has their own keyin an environment variable● model, people, systems, data  ● agent and harness  ● risk, stop, boundary
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

If a variable is unset and has no default, the config loads as is, and claude mcp list and /mcp show a warning. Claude Code credentials (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN) and several others read as empty in url and headers: copy the value to a variable with another name.

Takeaway
In this exampleThe repository holds ${API_KEY}, and every developer keeps the real key in their own environment variable.
In generalThat keeps the shared file safe to commit.
What to doRemove keys from .mcp.json and replace them with variables.

Where to start

claude mcp list1see the list2share via project3keys into variables● model, people, systems, data  ● agent and harness  ● risk, stop, boundary
Takeaway
In this exampleThree steps: look, share, hide the keys.
In generalFirst order in your own servers, then shared setup for the team.
What to doRun claude mcp list and find a server the whole team needs.

Same terms

© 2026 Egor Urvanov