Scope MCP Servers Globally or Per-Project

Not every MCP server belongs in every project. Claude Code lets you configure servers at user scope — available everywhere — or project scope — only for that specific repo.

~/.claude/settings.json     ← global: available in every project
.claude/settings.json       ← project: only available in this repo

A typical split:

// ~/.claude/settings.json — tools you always want
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "..." }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  }
}

// .claude/settings.json — tools specific to this repo
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://localhost/myapp_dev" }
    }
  }
}

Both configs are merged at runtime — project settings take precedence on conflicts. This means you can override a global server with a project-specific version if needed.

Global scope is ideal for utilities like web search, note-taking, or a shared filesystem tool. Project scope is right for database connections, internal APIs, or any server that requires project-specific credentials.

Scope your MCP servers like environment variables: global for utilities, local for project-specific secrets.