Project vs User Scope

When you wire an MCP server into Claude Code, the server definition has to live somewhere. There are two scopes, and choosing the wrong one is a classic architecture mistake.

• Project scope — .mcp.json at the repo root, committed to version control. Shared with the whole team.
• User scope — ~/.claude.json in your home directory. Personal, never shared via VCS.

The decision rule is simple: does everyone working on this repo need this server? If yes, it belongs in project scope.

Before scoping, recall what you're actually sharing. An MCP server exposes three primitive types:

• Tools — actions the model can invoke (query a DB, open a ticket).
• Resources — read-only data and context, like schemas or catalogs.
• Prompts — reusable templates.

When you commit a server to .mcp.json, every teammate instantly gets the same Tools, Resources, and Prompts — a shared, reproducible capability surface.