Claude Code stores each MCP server in one of three scopes. Local is private to you in one project, project is shared through a file in the repository, and user is private to you across every project. Pick the narrowest scope that does the job, and treat project scope as code that teammates will run.
The three scopes
According to Anthropic's documentation:
- Local (default). Stored in: The Claude config file under the project path. Who sees it: You, current project only.
- Project. Stored in: A file named .mcp.json in the repo root. Who sees it: Everyone with the repository.
- User. Stored in: The Claude config file. Who sees it: You, in all projects.
You choose the scope with a flag when adding a server.
claude mcp add --transport http shared-server --scope project https://example.com/mcp
Which scope to use
Local is the safe default for trying something out, or for a server that needs your own credentials in one repo.
Project suits a server the whole team needs, such as an internal docs search. Because it is committed, never put secrets in it. The documented format expands variables in the command, arguments, environment, URL and headers, so the file can reference a variable instead of a value.
User suits personal tools you want everywhere, like a notes server.
Precedence
If the same server name is defined in several places, the docs give the order local, then project, then user, then plugin, then claude.ai connectors. The whole entry from the winner is used, and fields are not merged. That means a local entry can silently override a team definition, which is worth knowing when debugging.
Approval for project servers
Claude Code asks you to approve servers from .mcp.json in interactive sessions, so cloning a repo does not start a server without your say. You can reset your choices, and you can block a server in every mode with a disable list in settings.
There is one caveat. In non-interactive runs, project servers load without a prompt. For scripts and CI, use the disable setting or the strict config option to keep unwanted servers out.
Review the whole picture
Anthropic's security page notes that reviewing .mcp.json does not show every server a session can load. Servers at other scopes, claude.ai connectors and plugins can add more. Run the list command and look at the full set.
For team rules, see Claude Code MCP deployments.
A worked example
Say your team wants a docs search server and you also want a personal notes server. Add the docs server with project scope, so the repository carries the definition and each person approves it once. Add the notes server with user scope, so it follows you between repositories but is never committed. If you want to try a third server only in one checkout, leave it at the default local scope and remove it when done. Keeping these three buckets clear makes later audits much easier.
Quick check
Where should a shared team server live?
In project scope, in the repository config file, without any secrets. Reference variables for tokens.
Why is my project server ignored?
A local or user entry with the same name wins, and the entries are not merged. Check precedence with the list command.
Sources
Last reviewed: 19 October 2026.
