[BUG] `--scope user` MCP servers are not truly user-wide; project configs override without inheritance

[jgoulah]

Description

MCP servers added with --scope user do not actually apply user-wide. There are two related issues:

Issue 1: Legacy ~/.claude.json no longer loads MCP servers

The old ~/.claude.json file (which had a top-level mcpServers key) was deprecated in v2.0.8, but:

• The documentation still references it in some places
• Users with existing configs there find their MCP servers suddenly stop working
• There was no clear migration path or notice

Issue 2: New location is project-specific, not user-wide

The --scope user flag now writes to ~/.claude/.claude.json under projects["<path>"].mcpServers, which means:

• Servers are tied to a specific project path (e.g., /Users/<user>/project1, /Users/<user>/project2)
• Child project paths with their own mcpServers key (even empty {}) override the parent
• There is no inheritance from parent project configs (eg. if you start claude in /Users/<user>/project1 but the mcp servers are defined for /Users/<user> the project1 does not inherit the parent config (evenif the mcpServers key is removed)

Steps to Reproduce

Reproducing Issue 1 (legacy file ignored):

1. Have MCP servers configured in ~/.claude.json under a top-level mcpServers key
2. Start Claude Code
3. Run /mcp → "No MCP servers configured"

Reproducing Issue 2 (no inheritance):

1. Add an MCP server with user scope:

   claude mcp add test-server --transport http https://example.com/mcp --scope user

2. Note it's stored in ~/.claude/.claude.json under projects["/Users/<user>"].mcpServers
3. Navigate to a subdirectory project (e.g., ~/dev/myproject)
4. Start Claude Code and run /mcp
5. Expected: Server appears (inherited from parent)
   Actual: "No MCP servers configured" (child project has "mcpServers": {})

Root Cause

In ~/.claude/.claude.json, MCP servers are stored per-project:

{
  "projects": {
    "/Users/user": {
      "mcpServers": {
        "my-server": { "type": "http", "url": "..." }
      }
    },
    "/Users/user/dev": {
      "mcpServers": {
        "chrome-devtools": {...}
      }  // MCP server overrides, but does not inherit from parent
    },
    "/Users/user/dev/project": {
      "mcpServers": {}  // Empty - also overrides, no inheritance, same if key is removed entirely
    }
  }
}

When Claude Code starts, it matches the most specific project path and uses that config with no inheritance. So each set of MCP Servers must be added to each project.

Expected Behavior

--scope user should mean "available in ALL projects" via one of:

1. True user-wide scope - a top-level mcpServers key that applies regardless of project configs
2. Inheritance - child projects inherit from parent project configs
3. No empty overrides - don't create empty mcpServers: {} entries that override parents

Current Workarounds

1. Manually add MCP servers to every project entry in ~/.claude/.claude.json
2. Always start Claude from a single parent directory
3. Remove mcpServers keys from child project entries (may get recreated)

Environment

• Claude Code Version: 2.1.1
• Platform: macOS
• Installation: npm (global)

Related Issues

• v2.0.31 recreates deprecated .claude.json files in real-time despite v2.0.8+ deprecation #10839 - v2.0.31 recreates deprecated .claude.json files
• Docs: Discrepancy in claude mcp add scope storage locations #6888 - Docs: Discrepancy in scope storage locations
• [FEATURE] Persistent user-level MCP configurations (enable/disable) #11085 - Persistent user-level MCP configurations
• MCP Configuration Inconsistency: CLI-managed vs File-based configs #3098 - MCP Configuration Inconsistency
• Documentation incorrect about MCP configuration file location #4976 - Documentation incorrect about MCP configuration file location

Impact

1. Breaking change without migration: Users with MCP servers in the old ~/.claude.json suddenly have no servers
2. Misleading flag: --scope user doesn't mean "user-wide"
3. Brittle config: Any new project dir can silently zero out your MCP servers
4. Poor DX: Users must manually manage config across every project

[github-actions]

Found 3 possible duplicate issues:

1. MCP servers persist in /mcp command despite removal via claude mcp remove #7936
2. Docs: Discrepancy in claude mcp add scope storage locations #6888
3. Feature Request: Support MCP server enablement in .claude/settings.local.json #16402

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[jgoulah]

#6888 is closest but seems outdated, and is more of a documentation related issue, this is more of a behavioral issue, even when stored correctly, --scope user doesn't work user-wide. They're complementary - #6888 is a prerequisite to understanding ours, but this addresses a different layer of the problem.

Summary

• Docs: Discrepancy in claude mcp add scope storage locations #6888 = "Where do configs go?" (docs are wrong about file locations)
• [BUG] --scope user MCP servers are not truly user-wide; project configs override without inheritance #16728 = "Why don't they work everywhere?" (child projects override parents without inheritance)

[Lellansin]

same here

[scottrepreneur]

This worked for me by setting these in a root-level "mcpServers" key. Tools are found in worktrees now.

~/.claude.json

{
   ...otherConfig,
   "projects": {
       ...projectConfigs,
   },
   "mcpServers": {
        "linear-server": {
           ...
         },
        "chrome-devtools": {
            ... 
         },
    }
}

Didn't try the cli flag, fwiw.