[BUG] Project-level MCP servers not loading in Claude Code runtime (v2.0.76)

Environment

Claude Code Version: 2.0.76
Operating System: Windows 10 (Build 19045.6456)
Shell: Git Bash (MINGW64) - GNU bash 5.2.37
Node.js: v22.14.0
Python: 3.10.19
Installation Method: npm global

---

Summary

Project-level MCP servers configured via .mcp.json or local config (~/.claude.json → projects."path".mcpServers) are not loading in Claude Code runtime.

Only user-level MCP servers work.

CLI commands deceptively show all servers as working, but MCP tools from project/local scopes are unavailable in Claude Code sessions.

---

Impact

CRITICAL - Breaks project-level MCP server feature:

• ❌ Cannot share project-specific MCP configs via .mcp.json
• ❌ Cannot use different MCP servers per project
• ❌ Blocks team collaboration on MCP configurations

---

Steps to Reproduce

1. Create .mcp.json in project root

{
  "mcpServers": {
    "test-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

2. Verify file is detected

$ claude
> /mcp

Observe: GUI shows .mcp.json path in "MCP Config locations"

• Project config (shared via .mcp.json):
  • <project>/.mcp.json

3. Check CLI (misleading!)

$ cd <project>
$ claude mcp list
test-server: https://example.com/mcp (HTTP) - ✓ Connected

Result: ✅ CLI shows server

4. Check GUI (broken!)

$ claude
> /mcp

Expected: Shows test-server in server list
Actual: ❌ Does NOT show test-server

5. Test MCP tools availability

In Claude Code session:

> Can you use test-server MCP tools?

Expected: Tools are available
Actual: ❌ Server not configured / tools unavailable

---

Test Matrix (Experimental Verification)

| Config Location | Config Path | CLI Shows? | GUI Shows? | Tools Work? |
|----------------|-------------|------------|------------|-------------|
| User-level | ~/.claude.json → mcpServers | ✅ Yes | ✅ Yes | ✅ Yes |
| Local config | ~/.claude.json → projects."path".mcpServers | ✅ Yes | ❌ No | ❌ No |
| Project config | <project>/.mcp.json → mcpServers | ✅ Yes | ❌ No | ❌ No |

---

Proof via Transfer Experiment

Hypothesis: Only user-level config works

Test: Move working server between scopes

Steps:

1. ✅ Created server in user-level → Works (appears in GUI, tools available)
2. ❌ Moved same server to .mcp.json → Broken (disappears from GUI, tools unavailable)
3. ✅ CLI still shows as "✓ Connected" → Misleading

After moving to .mcp.json:

• ✅ File exists and valid JSON
• ✅ GUI shows .mcp.json path in config locations
• ✅ CLI shows server as connected
• ❌ GUI doesn't list server
• ❌ MCP tools unavailable

Conclusion: .mcp.json is read by CLI but not loaded in runtime.

---

Configuration Examples

✅ Working (User-level)

// ~/.claude.json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_module"]
    }
  }
}

❌ Not Working (Project-level)

// <project>/.mcp.json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_module"]
    }
  }
}

Identical structure, but only user-level loads!

---

Observed Behavior

GUI Output

Manage MCP servers
3 servers  ← Only user-level

> 1. user-server-1  √ connected
  2. user-server-2  √ connected
  3. user-server-3  √ connected
  
MCP Config locations (by scope):
  • User config: ~/.claude.json
  • Project config: <project>/.mcp.json  ← Detected but not loaded!
  • Local config: ~/.claude.json [project: <project>]

Servers from .mcp.json are missing despite:

• .mcp.json exists and is valid
• GUI shows path to .mcp.json
• CLI shows servers as "✓ Connected"

---

Technical Analysis

Root Cause: CLI and runtime use different config loading mechanisms

Evidence:

• CLI (claude mcp list): ✅ Reads all scopes
• Runtime (GUI /mcp): ❌ Reads only user-level
• Runtime (tools): ❌ Only user-level tools available

Conclusion:

• Config files are readable (CLI proves this)
• Loading logic in runtime is broken (only user-level loads)

---

Workaround

Current solution: Use only user-level config

// ~/.claude.json
{
  "mcpServers": {
    // All servers here (no project isolation)
  }
}

Limitations:

• No project-specific configurations
• No team collaboration via .mcp.json
• All MCP servers global across all projects

---

Expected Behavior

Based on MCP documentation:

1. .mcp.json should load servers into Claude Code runtime
2. GUI /mcp should show servers from all scopes
3. MCP tools from all scopes should be available

---

Reproduction Rate

100% - Consistently reproducible (tested multiple times with server transfers)

---

Related Issues

• #13898 - Custom subagents cannot access project-scoped MCP servers (similar symptoms)

---

Request

Project-level MCP configurations are documented but non-functional.

Please fix loading mechanism so .mcp.json and local config work as documented.