Claude Code MCP Global vs Project Config: When to Use Each

Here's the question I get most from teams adopting Claude Code: "Where should I put the Postgres skill?" The answer depends on who needs it and whether there are secrets involved. Let me walk through the logic.

The Two Locations

Global Config — Your Personal Toolkit

Think of global config as your personal workspace. Anything in here follows you across every project you open with Claude Code.

Good fits for global config:

• Weather, calculator, notes — 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

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@trustedskills/weather-mcp"]
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@trustedskills/web-search-mcp"],
      "env": { "SEARCH_API_KEY": "your-personal-key" }
    }
  }
}

Project Config — Team Tools via Git

Project config's superpower is that it lives in your repo. Commit it, push it, and every team member who clones the repo has the same tools automatically.

Good fits for project config:

• 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

Project config example

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@trustedskills/postgres-mcp"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

Each developer sets their own DATABASE_URL in their shell or a gitignored .env file. The config commits safely — no actual credentials in the repo.

Global vs Project: The Decision Matrix

The Decision Checklist

1. Should the whole team have this? → Project config
2. Does it use your personal credentials? → Global config
3. Do you want it in every project? → Global config
4. Is it specific to this project's infrastructure? → Project config

Frequently Asked Questions

What happens if the same skill is in both global and project config?

Project config takes precedence. The project version is used when you're working in that project. This lets you override global defaults on a per-project basis.

Can I commit the project config to git without exposing secrets?

Yes — use ${VAR_NAME} references and keep actual values in your local shell environment or a gitignored .env file. The config file itself contains no secrets.

How do I add a project-scoped skill via the CLI?

Use the --project flag: claude mcp add my-tool --project -- npx -y @package/name. This writes to .claude/settings.json in your current directory.