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

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:

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

1. Note it's stored in ~/.claude/.claude.json under projects["/Users/<user>"].mcpServers
2. Navigate to a subdirectory project (e.g., ~/dev/myproject)
3. Start Claude Code and run /mcp
4. 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

• #10839 - v2.0.31 recreates deprecated .claude.json files
• #6888 - Docs: Discrepancy in scope storage locations
• #11085 - Persistent user-level MCP configurations
• #3098 - MCP Configuration Inconsistency
• #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