Claude Code MCP Global vs Project Config: When to Use Each
Claude Code MCP global project config explained — when to use global vs project-level settings, how to safely share skills with your team via git, and how to handle secrets across environments.
Last updated 27 September 2026
User scope (claude mcp add --scope user, stored in ~/.claude.json) = personal tools, your credentials, things you want everywhere. Project scope (claude mcp add --scope project, stored in .mcp.json) = team tools you commit to git. Never put API keys directly in .mcp.json. Use ${VAR} references instead.
When you add an MCP server to Claude Code, you choose who gets it: only you, or everyone who clones the repo. The answer depends on who needs the tool and whether it uses a secret.
The Three Scopes
| Scope | Where it is stored | Who gets it |
|---|---|---|
User (--scope user) |
~/.claude.json |
Only you, in all projects on this machine |
| Local (default) | ~/.claude.json, under the current project |
Only you, only in this project |
Project (--scope project) |
.mcp.json in the project root |
Everyone who clones the repo |
On Windows, ~ is your user folder, for example C:\Users\YourName\.claude.json. claude mcp add does not write to ~/.claude/settings.json or .claude/settings.json. Those files hold other Claude Code settings.
User Scope — Your Personal Toolkit
A user-scoped server follows you into every project you open with Claude Code. Nobody else gets it.
Good fits for user scope:
- Notes or memory tools you want everywhere
- Web search with your personal API key
- GitHub tool with your personal access token
- Any tool using credentials that are yours, not the project's
claude mcp add --scope user memory -- npx -y @modelcontextprotocol/server-memory
claude mcp add --scope user brave-search -e BRAVE_API_KEY=your-personal-key -- npx -y @brave/brave-search-mcp-serverClaude Code writes these to ~/.claude.json. That file is never inside your repo, so the key is not committed.
Project Scope — Team Tools via Git
A project-scoped server lives in .mcp.json in your repo. Commit it, and everyone who clones the repo gets the same server. Claude Code asks each person to approve a project server the first time it sees it.
Good fits for project scope:
- Database tools pointing to the project's dev DB
- Project-specific validators or code generators
- Any tool that should be the same for all developers on the team
.mcp.json example
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@brave/brave-search-mcp-server"],
"env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
}
}
}Claude Code replaces ${BRAVE_API_KEY} with the value of that environment variable when it starts the server. Each developer sets their own BRAVE_API_KEY in their shell before running claude. Claude Code does not read a .env file for you. The committed file holds no credentials.
${VAR_NAME} references in .mcp.json and set the real values in your own environment.
User vs Project: The Decision Matrix
| User scope | Project scope | |
|---|---|---|
| Team sharing | Not possible (per-machine) | Easy via git commit |
| Personal credentials | Safe — never committed | Risky — don't put secrets here |
| Project-specific tools | Clutters every project | Good fit |
| Priority when both exist | Lower | Higher (only local scope beats it) |
The Decision Checklist
- Should the whole team have this? → Project scope
- Does it use your personal credentials? → User scope
- Do you want it in every project? → User scope
- Is it specific to this project's infrastructure? → Project scope
Frequently Asked Questions
What happens if the same server is in both user and project scope?
The project entry wins. A local entry with the same name would beat both. Claude Code uses the whole entry from the winning scope.
Can I commit .mcp.json to git without exposing secrets?
Yes. Use ${VAR_NAME} references and set the real values in your shell environment. The file itself holds no secrets.
How do I add a project-scoped server via the CLI?
Use --scope project: claude mcp add --scope project my-tool -- npx -y @package/name. This writes to .mcp.json in your project root, which you can commit.
TrustedSkills Team
The TrustedSkills team maintains the TrustedSkills index of AI agent skills. The index records where each skill comes from and how to install it. It does not review or audit skill code.