Choose project or personal MCP scope

Learning objective

Choose project-scoped .mcp.json for shared MCP servers and user-scoped ~/.claude.json for personal experiments.

Core idea

Choose an MCP server’s scope from who needs its configuration and where it should load. A team’s issue tracker belongs in project configuration when everyone working in that repository needs the same integration. A personal utility used across repositories belongs in user configuration. A private experiment confined to one repository belongs in local configuration.

The filename alone does not identify the scope. Claude Code stores both local-scoped and user-scoped servers in ~/.claude.json. Local entries sit under a project’s path; user entries apply across projects. Keeping these meanings separate prevents an experiment from appearing in unrelated work or a shared integration from existing only on its author’s machine.

Scope determines configuration sharing and loading. It does not supply credentials or establish permission to execute every tool. See 2.4.2 for credential expansion and 0.6 for availability versus approval.

How it works

Choose among three scopes

Claude Code’s MCP installation scopes are local, project, and user. Local is the default for claude mcp add. Without an explicit scope, adding a server from a repository creates a private configuration for that project, not a shared team configuration.

Project scope stores entries under mcpServers in .mcp.json at the project root. Adding a server with --scope project creates or updates that file. You can commit the configuration so teammates receive the same server definition. Keep authentication values out of the committed entry; sharing an endpoint and tool contract does not require sharing a token.

User scope stores the configuration in ~/.claude.json and makes it available across your projects. Add --scope user when that reach is intentional. Local scope also uses ~/.claude.json, but under projects and the absolute project path. Do not confuse it with .claude/settings.local.json, the location for general local settings.

These example commands select different loading scopes for an illustrative HTTP endpoint:

claude mcp add --transport http team-issues \
  --scope project https://issues.example.com/mcp
claude mcp add --transport http personal-docs \
  --scope user https://docs.example.com/mcp

Replace the example URLs with your approved servers’ documented MCP endpoints. The commands write configuration; an Added ... response does not prove the server connected. Use claude mcp get team-issues or claude mcp list to examine status, and /mcp inside an interactive session to manage connections and authentication.

Understand duplicate definitions

For matching server names across the three scopes, local takes precedence over project, and project takes precedence over user. Claude Code uses the complete winning entry; it does not merge its fields with lower-precedence definitions. A local experiment named team-issues can therefore replace the shared endpoint and authentication configuration for that developer.

This is a troubleshooting rule, not a reason to create shadow configurations. When a teammate receives different tools from the supposedly shared integration, inspect the active definition before changing tool descriptions. Different servers behind the same configuration name can explain the difference.

The documentation also describes plugin and connector precedence and managed configuration. Those sources can affect the effective server set, so the three installation scopes are not a complete organization-wide policy model. In the Desktop app’s Code tab, a same-named stdio entry at the top level of ~/.claude.json takes precedence over .mcp.json; do not assume the terminal’s project-over-user rule describes that surface.

Account for approval and automated runs

In interactive terminal sessions, Claude Code prompts before using project-scoped servers from .mcp.json. claude mcp reset-project-choices resets those approval choices. A configuration committed by a repository does not, by itself, authorize that repository to approve its own servers before workspace trust.

In claude -p, Agent SDK, and cloud sessions, Claude Code cannot show that interactive prompt and loads project servers without asking. To block a project server in every permission mode, use disabledMcpjsonServers. For an explicitly supplied server set, --strict-mcp-config makes Claude Code use only servers passed with --mcp-config, subject to managed configuration. Approval behavior is therefore a separate consideration from whether the file is shareable.

A disabledMcpjsonServers entry blocks a project server in every mode; otherwise the session decides whether Claude Code asks before using it.

The Agent SDK can load .mcp.json through project settings. The MCP documentation says default query() options enable the project setting source. If you set TypeScript settingSources explicitly, include "project" to load the file. You can instead configure servers directly through TypeScript mcpServers or Python mcp_servers; see 2.4.3 for discovery in those workflows.

Key distinctions and trade-offs

The following choices separate team reach from personal reach:

Project scope makes the integration reviewable in version control. User scope avoids adding personal configuration to a repository but broadens where it loads. Local scope keeps an experiment private and project-specific. None of these choices makes an untrusted server trustworthy or repairs missing authentication.

Architecture / decision scenario

A developer productivity team wants one issue integration for its application repository. An engineer also evaluates a documentation server and uses a personal notes service across several projects.

The issue integration goes into .mcp.json with --scope project, and its credentials use the expansion described in 2.4.2. The notes service uses --scope user. The documentation experiment uses --scope local because the engineer wants to test it only in this repository.

A teammate reports that the issue integration points at a test endpoint. claude mcp list and /mcp warn when one server name has different endpoints in more than one scope, and the warning reveals a same-named local entry in ~/.claude.json. The team removes that experiment with claude mcp remove team-issues --scope local instead of editing the shared definition to compensate. It then checks claude mcp get for the selected server and verifies connection status. For automated review runs, it separately decides which project servers to admit rather than relying on an approval dialog that cannot appear.

Common exam traps

• Treating every entry in ~/.claude.json as user-scoped.
• Assuming the default claude mcp add scope shares a server with teammates.
• Blaming the server when a teammate lacks its tools, although it was added at local or user scope.
• Expecting fields from local and project entries to merge.
• Treating an Added ... response as proof of connectivity.
• Assuming interactive project approval also occurs in headless or SDK runs.

Where the exam guide differs

What to remember

Use project scope for shared repository tooling, user scope for personal tooling across repositories, and local scope for private project experiments. Inspect the selected definition and connection status separately. The storage file, configuration reach, credentials, and tool permissions answer different questions.

Knowledge check

References

• Anthropic, Connect Claude Code to tools via MCP
• Anthropic, Connect to external tools with MCP
• Anthropic, Claude Certified Architect – Foundations Exam Guide