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:
~/.claude/settings.json→mcpServerskey (added viaclaude mcp add --scope user)~/.mcp.json— global shared MCP config (newer format)
Actual behavior
Claude Code went through a lengthy, unfocused exploration:
- Read
settings.jsonlooking formcpServers(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.jsonby accident viafind
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 listoutput (or--help) references these file paths so users and the model can locate them immediately
This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗