[BUG] User-scoped MCP servers in .claude.json never launch when using CLAUDE_CONFIG_DIR

Resolved 💬 3 comments Opened Apr 15, 2026 by dyresen Closed Apr 15, 2026

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:

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

  1. 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":[]}'
``

  1. Verify it's stored in ~/.claude-alt/.claude.json under the top-level mcpServers key.
  1. Start a session with the wrapper and run /mcp.
  1. The server shows up in the list but status is failed. Pressing r to reconnect says "Failed to reconnect".
  1. 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:

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

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

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

  1. 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

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗