[BUG] User-scoped MCP servers in .claude.json never launch when using CLAUDE_CONFIG_DIR
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
- Create a wrapper script that uses a custom config directory:
``bash``
#!/bin/bash
export CLAUDE_CONFIG_DIR=~/.claude-alt
claude "$@"
- Add an MCP server via the wrapper:
``bash``
./claude-alt mcp add-json --scope user my-mcp-server \
'{"type":"stdio","command":"/path/to/mcp-server.sh","args":[]}'
- Verify it's stored in
~/.claude-alt/.claude.jsonunder the top-levelmcpServerskey.
- Start a session with the wrapper and run
/mcp.
- The server shows up in the list but status is failed. Pressing
rto reconnect says "Failed to reconnect".
- 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 useralso silently drops thecwdfield 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:
- Create
.mcp.jsonin the project root:
``json``
{
"mcpServers": {
"my-mcp-server": {
"command": "/absolute/path/to/mcp-server.sh",
"args": []
}
}
}
- In
$CLAUDE_CONFIG_DIR/.claude.json, find the project entry and add:
``json``
"enabledMcpjsonServers": ["my-mcp-server"]
- 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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗