[Bug] MCP configuration file location detection and safety issues with .claude.json

Bug Description
Subject: MCP Configuration UX Issues & File Safety Concerns

Category: Configuration & Documentation

Description:

I encountered significant confusion with MCP server configuration that exposed both UX and safety issues:

Issue 1: Confusing MCP Configuration File Locations

Problem: Claude Code accepts MCP configurations in multiple locations, but the documentation and error messages don't
clearly explain which file is used when:

• ~/.claude.json (user scope - actual location used, contains mcpServers field)
• ~/.claude/mcp.json (looks valid, inside .claude directory, but silently ignored)
• <project>/.mcp.json (project scope)

What happened: I had a valid MCP configuration at C:\Users\walraveng\.claude\mcp.json. When running /mcp, it reported
"No MCP servers configured" with zero indication that:

• It was looking in a different location
• My config file existed but was being ignored
• Where I should actually put the configuration

Expected behavior:

1. /mcp or /doctor should detect MCP configs in unsupported locations and warn: "Found mcp.json in ~/.claude/ but this

is not a valid location. User-scoped MCP servers should be in ~/.claude.json under the 'mcpServers' field, or use .mcp.
json at your project root."

1. Documentation should clearly show the file structure difference between .claude.json (user settings + MCP servers)

vs .mcp.json (project MCP only)

Issue 2: File Safety Risk During Troubleshooting

Problem: The .claude.json file contains critical data (authentication, usage history, project settings, tips history,
etc.) but:

• Has no backup mechanism
• Can be easily corrupted/overwritten during troubleshooting
• No warning about data loss when editing

What happened: While troubleshooting the MCP issue, I (Claude) attempted to copy ~/.claude/mcp.json to ~/.claude.json,
which would have completely overwritten 919 bytes of configuration data with 357 bytes, losing all user history and set
tings.

Risk: Users troubleshooting MCP issues could easily:

• Accidentally overwrite .claude.json
• Corrupt the JSON structure
• Lose authentication tokens, usage history, and project settings

Suggested improvements:

1. Automatic backups: Create .claude.json.backup before any programmatic modifications
2. Validation: When .claude.json is modified, validate the JSON structure and restore from backup if corrupted
3. Merge helpers: Provide a safe claude mcp import <file> command that merges MCP config into existing .claude.json wi

thout overwriting other fields

1. Warning in docs: Clearly document that .claude.json is critical and should not be manually replaced

Issue 3: Poor Error Messages

The /mcp command's "No MCP servers configured" message provides no actionable guidance:

• Doesn't explain where it's looking
• Doesn't suggest how to configure servers
• Doesn't link to documentation

Suggested improvement:
No MCP servers configured.

To add MCP servers:

• User scope: Add "mcpServers" field to ~/.claude.json
• Project scope: Create .mcp.json at project root
• Run: claude mcp add --help

See: https://code.claude.com/docs/en/mcp

Impact

These UX issues make MCP configuration unnecessarily difficult and risky, especially for users following outdated exam
ples or migrating configurations between projects.

---
Priority: Medium-High (affects MCP adoption and can cause data loss)

Suggested Quick Win: Update /doctor command to detect and warn about common MCP misconfigurations.

Environment Info

• Platform: win32
• Terminal: null
• Version: 2.0.76
• Feedback ID:

Errors

[{"error":"AxiosError: Request failed with status code 403\n    at bx (file:///C:/Users/walraveng/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/cli.js:56:1137)\n    at Unzip.<anonymous> (file:///C:/Users/walraveng/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/cli.js:57:9852)\n    at Unzip.emit (node:events:520:35)\n    at Unzip.emit (node:domain:489:12)\n    at endReadableNT (node:internal/streams/readable:1701:12)\n    at process.processTicksAndRejections (node:internal/process/task_queues:89:21)\n    at fzA.request (file:///C:/Users/walraveng/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/cli.js:59:2130)\n    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)\n    at async UT2 (file:///C:/Users/walraveng/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/cli.js:1845:3609)","timestamp":"2025-12-30T10:45:47.328Z"},{"error":"Error: Failed to create shell snapshot: Command failed: C:\\Program Files\\Git\\bin\\bash.exe -c -l SNAPSHOT_FILE='C:\\Users\\walraveng\\.claude\\shell-snapshots\\snapshot-bash-1767091544172-thxl2g.sh'\n      # No user config file to source\n\n      # First, create/clear the snapshot file\n      echo \"# Snapshot file\" >| \"$SNAPSHOT_FILE\"\n\n      # When this file is sourced, we

Note: Error logs were truncated.