- In short
- MCP configuration scope is the setting that controls where a Model Context Protocol server definition is stored, which projects load it, and whether teammates inherit it. Project scope writes to a version-controlled .mcp.json at the repo root; user scope writes to your personal ~/.claude.json and stays private to you.
What MCP configuration scope means
MCP configuration scope is the setting that decides where a Model Context Protocol server definition is stored, which projects load it, and whether your teammates inherit it. Pick the wrong scope and the symptom is predictable: either a server that should be private leaks into a shared file, or a server the whole team needs lives somewhere only you can reach. Getting the mcp configuration scope right is the first design decision in any MCP integration, which is why Domain 2 of the Claude Certified Architect exam puts it at the root of the tool-design knowledge points.
The reason scope matters so much is that an MCP server is not just a setting, it is a capability you are granting to the agent. Where you store that grant determines its blast radius. A database server scoped to one repository is a tidy, reviewable decision; the same server pasted into your global config quietly attaches to every project you open, including ones that have no business touching that database.
- MCP configuration scope
- The level at which a Model Context Protocol server is registered in Claude Code. It controls the storage file, the set of projects that load the server, and whether the configuration is shared with the team through version control.
The three scopes: local, project, and user
Claude Code supports three installation scopes, and the exam expects you to know what each one stores and shares.
- Local scope is the default. The server loads only in the current project and stays private to you. It is stored in your home-directory
~/.claude.jsonunder that project's path, so it never appears in your other projects and is never shared. Use it for personal experiments and throwaway servers. - Project scope writes the server into a
.mcp.jsonfile at the repository root. That file is designed to be committed to version control, so everyone who clones the repo inherits the same servers. This is the only scope that shares a configuration with the team. - User scope is also stored in
~/.claude.json, but it loads across all of your projects on the machine. It is private to your user account, ideal for personal utility servers you reach for everywhere, such as a documentation search server.
A subtlety worth remembering: in older versions of Claude Code the scope now called local was called project, and user was called global. The exam uses the current names, but the renaming is a common source of confusion in tutorials written a year apart.
A picture of where each scope lives
Why .mcp.json is the team-sharing scope
The whole point of project scope is collaboration. When you add a project-scoped server, Claude Code creates or updates .mcp.json at the repository root in a standardized format. Because that file is part of the repository, it is reviewed in pull requests, versioned alongside the code, and cloned by every contributor. A new engineer who joins the team gets the project's MCP servers for free, the moment they check out the branch.
For security, Claude Code does not silently trust servers it finds in a freshly cloned .mcp.json. It prompts each user to approve project-scoped servers before they run, and you can reset those approval choices later if you need to re-review them. That approval step is the safeguard that makes shipping servers through version control safe: the configuration travels, but execution still requires a human to say yes.
This is the design the exam rewards. If a scenario describes a team that needs everyone to have the same Jira or Postgres server, the answer is project scope and a committed .mcp.json, not asking each engineer to configure it by hand.
Precedence: which definition wins
Because the same server name can appear in more than one scope, Claude Code needs a tie-breaker. It connects to a server once, using the definition from the highest-precedence source, and it does not merge fields across scopes. The order, highest first, is local, then project, then user.
That ordering has a practical use. A teammate can override a shared project server locally, for example pointing a database server at a personal sandbox, without editing the committed .mcp.json that everyone else relies on. The shared definition stays intact in the repo; the local definition simply takes precedence on that one machine.
A quick rubric for choosing a scope
Most scope decisions resolve in a single question: does anyone other than you need this server? If the answer is yes, it belongs at project scope, so the committed .mcp.json carries it to the whole team. If the answer is no, the only thing left to decide is whether you want it in this one project or in all of them. Just this project means local scope; everywhere you work means user scope. That three-way split, team versus this-project versus all-my-projects, covers the overwhelming majority of real cases without any further deliberation.
A few rules of thumb sharpen the edges. Anything that carries a shared, non-secret endpoint the team depends on, a staging database, an internal API, a project-specific service, leans toward project scope. Anything personal, a scratch server, an experiment, or a tool only you happen to like, leans toward local or user scope. And anything whose credentials you are not yet ready to manage through environment variables should stay out of the shared .mcp.json until you are, because a shared file is the wrong place to discover that you hardcoded a secret.
Scope, approval, and the enterprise level
Scope does not act alone; it works alongside the approval and trust mechanisms that keep shared servers safe. A project-scoped server that arrives through a freshly cloned repository is not executed on sight. Claude Code surfaces it for approval and waits, so the act of sharing a configuration is always separated from the act of granting it permission to run. This is what lets teams distribute powerful servers through version control without turning a routine pull into an automatic grant of new capabilities.
Beyond the three personal and project scopes, administrators can deploy servers at an enterprise level through managed configuration, which is how an organization standardizes a baseline set of servers across many machines. For the foundations exam you mainly need the local, project, and user trio and their precedence, but it helps to know the enterprise layer exists, because it explains how a company can guarantee that every engineer starts from the same approved set of integrations rather than assembling one server at a time.
The throughline across all of this is intent. Scope is the mechanism by which you declare who a server is for, and every other behavior, precedence, approval, and enterprise rollout, follows from that declaration. Decide who the server is for first, and the correct scope is rarely in doubt.
What scope does not change
It is worth being precise about the limits of scope, because the exam likes to probe the boundary. Scope determines where a server is stored, which projects load it, and who inherits it. It does not change what the server can do once it runs, it does not merge fields between two definitions of the same server, and it does not alter the server's own permissions or the credentials it uses. A user-scoped server and a project-scoped server pointing at the same endpoint are identical in capability; they differ only in reach and sharing. Keeping that line clear, reach and sharing on one side, behavior and capability on the other, stops you from reaching for a scope change when the real fix is a credential, a description, or an approval.
Why MCP configuration scope matters for the exam
Task statement 2.4 sits inside Domain 2, Tool and MCP Integration Design, and this knowledge point is its foundation: the later KPs on environment variables, resources, and build-versus-use decisions all assume you already know where a server is configured. Questions at the remember Bloom level rarely ask you to recite file paths in the abstract. Instead they describe a workflow problem, a teammate who cannot see a server, a credential that ended up in a shared file, a server that loaded in the wrong project, and ask you to name the scope mistake behind it. Every one of those traces back to the same map: shared and version-controlled means project scope and .mcp.json; private to you means local or user scope and ~/.claude.json.
Worked example
A four-person team wants everyone to query the same staging Postgres database through an MCP server, and one engineer also wants a personal scratch database that nobody else should see.
Start with the shared requirement. Because every teammate needs the staging database server, it belongs in project scope. One engineer runs the add command with project scope, which writes the server into .mcp.json at the repo root, and opens a pull request. Reviewers can see exactly what capability is being granted, the change merges, and the next time each teammate pulls the branch Claude Code prompts them once to approve the new project-scoped server. From then on all four engineers share an identical configuration with zero manual setup.
Now the private requirement. The scratch database must not appear for anyone else, so it does not go anywhere near .mcp.json. The engineer adds it at local scope (or user scope if they want it in every project they touch), which stores it in their own ~/.claude.json. Nobody else's clone is affected because that file never leaves their machine.
What if the two servers happen to share a name? Precedence resolves it cleanly. On that one engineer's machine the local definition outranks the project definition, so their scratch database wins locally, while every other teammate still gets the shared staging server from the repo. The team-wide configuration in version control is never touched, which is precisely the separation of concerns the scope hierarchy is designed to give you.
Common misreadings to avoid
Misconception
Putting a server in user-level config is a convenient way to share it with the whole team.
What's actually true
Misconception
A project-scoped server in .mcp.json runs automatically as soon as a teammate clones the repository.
What's actually true
How it shows up on the exam
Your team keeps reporting that a new engineer cannot use the GitHub MCP server everyone else has. You added it months ago by running the add command without thinking about scope, and it has always worked on your machine across every repo you open. What is the most likely cause?
People also ask
What is the difference between project and user MCP scope?
Where is the .mcp.json file stored?
Are MCP servers shared with my team automatically?
What is the default MCP scope in Claude Code?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
MCP servers with Claude Code
Why watch: Configuring MCP servers via project versus user files is precisely the .mcp.json scoping hierarchy this KP covers.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.