MCP Config Scopes

Definition

In Claude Code, where an MCP server definition lives determines its scope: .mcp.json is project-scoped and shared via the repo, while ~/.claude.json is user-scoped.

Key points

• .mcp.json = project-scoped, committed to the repo, shared with the team.
• ~/.claude.json = user-scoped (global), also holds OAuth / trust state.
• This is distinct from the API MCP connector, which configures servers inline in the request — see MCP Connector.
• Fits the broader Claude Code precedence model — see Config Hierarchy.

Why it matters for the exam

• Tests where to put a server so teammates get it automatically (.mcp.json) vs a personal server (~/.claude.json).
• Distinguishes file-based Claude Code MCP config from the API connector.

Common gotchas

• A server only you need does not belong in the committed .mcp.json.
• ~/.claude.json (user MCP/OAuth/trust) is different from ~/.claude/settings.json (settings) — see Config Hierarchy.

See also

• MCP Connector
• Config Hierarchy
• MCPToolset Allowlist and Denylist

Sources

• docs-tools-agents
• netlight-study-guide