mcpServers in project settings should merge with global settings, not replace

Resolved 💬 3 comments Opened Jan 10, 2026 by joelvogt Closed Jan 14, 2026

Problem

When a project-level .claude/settings.json defines an mcpServers block, it completely replaces the global ~/.claude/settings.json mcpServers instead of merging with them.

Expected Behavior

Project-level mcpServers should merge with global settings, allowing:

  • Global MCP servers to remain available across all projects
  • Project-specific servers to be added on top

Current Behavior

Defining any mcpServers in project settings causes all global MCP servers to become unavailable. Users must duplicate their global MCP server configs into every project that defines its own servers.

Reproduction Steps

  1. Define an MCP server in ~/.claude/settings.json:
{
  "mcpServers": {
    "cloudflare-dns": {
      "command": "npx",
      "args": ["mcp-remote", "https://dns-analytics.mcp.cloudflare.com/mcp"]
    }
  }
}
  1. In a project, define .claude/settings.json with project-specific servers:
{
  "mcpServers": {
    "my-project-server": {
      "command": "uv",
      "args": ["run", "my-server"]
    }
  }
}
  1. Start Claude Code in that project
  2. Observe that cloudflare-dns is not available - only my-project-server connects

Suggested Fix

Merge mcpServers from all config levels (global → project → local), with more specific configs taking precedence for servers with the same name.

Workaround

Manually copy all global MCP server definitions into each project's settings.json.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗