claude-code - 💡(How to fix) Fix [BUG] User-scoped MCP servers in .claude.json never launch when using CLAUDE_CONFIG_DIR [2 comments, 2 participants]

Description

When using CLAUDE_CONFIG_DIR to point Claude Code at a non-default config directory (e.g., ~/.claude-jobb instead of ~/.claude), user-scoped MCP servers configured in the top-level mcpServers section of .claude.json are shown in /mcp but never actually launched. The process is never spawned — no connection attempt is made at all.

Steps to reproduce

1. Create a wrapper script that uses a custom config directory:

   #!/bin/bash
   export CLAUDE_CONFIG_DIR=~/.claude-alt
   claude "$@"

2. Add an MCP server via the wrapper:

   ./claude-alt mcp add-json --scope user my-mcp-server \
     '{"type":"stdio","command":"/path/to/mcp-server.sh","args":[]}'

3. Verify it's stored in ~/.claude-alt/.claude.json under the top-level mcpServers key.

4. Start a session with the wrapper and run /mcp.

5. The server shows up in the list but status is failed. Pressing r to reconnect says "Failed to reconnect".

6. The MCP server process is never spawned (verified by wrapping the command in a debug script that logs to /tmp — no log file is created).

Additional observations

• claude mcp add-json --scope user also silently drops the cwd field from the JSON config.
• Plugin-provided MCP servers (e.g., from marketplace plugins) work fine in the same session.
• The same MCP server works perfectly when tested manually from the terminal.

Workaround

Use a project-level .mcp.json file instead, and pre-approve it by manually adding the server name to enabledMcpjsonServers in the project entry within .claude.json:

1. Create .mcp.json in the project root:

   {
     "mcpServers": {
       "my-mcp-server": {
         "command": "/absolute/path/to/mcp-server.sh",
         "args": []
       }
     }
   }

2. In $CLAUDE_CONFIG_DIR/.claude.json, find the project entry and add:

   "enabledMcpjsonServers": ["my-mcp-server"]

3. Restart Claude Code — the server connects successfully.

Environment

• Claude Code version: 2.1.109
• OS: macOS (Darwin 25.4.0, arm64)
• Shell: zsh
• Use case: Separating work and personal Claude Code configurations via CLAUDE_CONFIG_DIR

Related issues

• #4938 — Multiple mcpServers sections silently override each other
• #15797 — MCP configuration file location detection issues
• #5037 — MCP servers in .claude/.mcp.json not loading properly