MCP servers can be configured at two levels. Project-level (.mcp.json) is shared with the team via version control. User-level (~/.claude.json) is personal and local. Choose the right scope based on who needs the server.
Project scope: .mcp.json
Place .mcp.json at the project root. Commit it to version control. Every team member who clones the repo automatically gets the MCP server configuration.
Use for: team-shared integrations (GitHub, Jira, Slack, project database, CI tools). Everyone on the project needs these servers.
User scope: ~/.claude.json
Configure in the user’s home directory. Not version-controlled. Only affects one developer.
Use for: personal tools (personal notes MCP, custom productivity tools), servers with personal credentials that shouldn’t be shared.
Not in CLAUDE.md
CLAUDE.md provides instructions to Claude, not MCP server configuration. “Use the GitHub MCP server” in CLAUDE.md doesn’t configure the server — it’s just text. MCP servers are configured in .mcp.json (project) or ~/.claude.json (user).
Secrets management
Project-level .mcp.json is committed to git, so secrets must not be hardcoded. Use ${ENV_VAR} syntax: each developer sets their own token locally, and the config file contains only the variable reference.
One-liner: Team-shared MCP servers go in .mcp.json at the project root (committed to git); personal servers go in ~/.claude.json — CLAUDE.md provides instructions, not server configuration.