docs: claude code doesn't know user-level MCP config locations

Resolved 💬 5 comments Opened Mar 9, 2026 by devseunggwan Closed Apr 6, 2026

Problem

When asked to inspect or migrate user-level MCP settings, Claude Code did not immediately know the canonical storage locations and instead explored many unrelated files before finding the answer.

Expected behavior

Claude Code should know (and document clearly) that user-level MCP server configurations are stored in:

  1. ~/.claude/settings.jsonmcpServers key (added via claude mcp add --scope user)
  2. ~/.mcp.json — global shared MCP config (newer format)

Actual behavior

Claude Code went through a lengthy, unfocused exploration:

  • Read settings.json looking for mcpServers (correct but no result)
  • Ran claude mcp list (returned nothing)
  • Browsed ~/.claude/ directory listing
  • Checked settings.local.json, plugin caches, ToolHive configs
  • Eventually found ~/.mcp.json by accident via find

Suggestion

  • Add a concise knowledge entry or inline comment in the codebase/docs that explicitly states the two canonical locations for user-level MCP config
  • Ensure claude mcp list output (or --help) references these file paths so users and the model can locate them immediately

View original on GitHub ↗

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