MCP config hierarchy is confusing and undocumented when using CLAUDE_CONFIG_DIR profiles

Summary

When using CLAUDE_CONFIG_DIR to set up multiple profiles (e.g., claude-sungjun, claude-unicorn), the MCP server configuration hierarchy is extremely confusing and largely undocumented. I spent 3+ hours debugging which config files are actually loaded.

Test Results

I systematically tested 6 config locations by placing unique test MCP entries in each:

| Location | File | Loaded? |
|---|---|---|
| Global mcp.json | ~/.claude/mcp.json | NO |
| Profile mcp.json | ~/.claude-profiles/{profile}/mcp.json | NO |
| Project .mcp.json | .mcp.json in project root | YES (as "Project MCPs") |
| Global .claude.json mcpServers | ~/.claude.json → mcpServers | NO |
| Profile .claude.json mcpServers | {CLAUDE_CONFIG_DIR}/.claude.json → mcpServers | YES (as "User MCPs") |
| Local .claude.json project mcpServers | ~/.claude.json → projects[path].mcpServers | NO |

Only 2 out of 6 locations actually work.

Issues

1. ~/.claude/mcp.json is completely ignored when using profiles — this is the file that claude mcp add documentation suggests editing
2. Profile mcp.json is ignored — even though it exists in the profile directory structure
3. Ghost MCP servers: Once an MCP server is added to ~/.claude.json mcpServers and later removed, it persists as a "connected" server across all projects. claude mcp remove says it doesn't exist in any scope, but claude mcp list still shows it. Cannot be removed.
4. No documentation about how CLAUDE_CONFIG_DIR profiles interact with MCP config resolution

Expected Behavior

• Clear documentation on which files are loaded when using profiles
• ~/.claude/mcp.json or profile mcp.json should work as "User MCPs"
• Ghost servers should be removable via claude mcp remove

Environment

• Claude Code v2.1.92
• macOS Darwin 24.6.0
• Using CLAUDE_CONFIG_DIR for profile switching

🤖 Generated with Claude Code