[DOCS] Add warning that mcpServers in settings.json / settings.local.json is silently ignored

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

MCP Server Configuration / Installing MCP servers

Current Documentation

The docs have a note that says:

"Where are MCP servers stored?

• User and local scope: ~/.claude.json
• Project scope: .mcp.json in your project root"

And another note:

"The term 'local scope' for MCP servers differs from general local settings. MCP local-scoped servers are stored in ~/.claude.json (your home directory), while general local settings use .claude/settings.local.json (in the project directory)."

This information is correct but buried deep in the page with no explicit warning about the wrong files.

What's Wrong or Missing?

There is no warning that placing mcpServers in ~/.claude/settings.json or ~/.claude/settings.local.json will be silently ignored — no error, no log, nothing.

Since settings.json handles permissions and settings.local.json handles hooks, it's natural to assume MCP servers belong there too. Both files accept the mcpServers JSON key without any validation error, making the misconfiguration completely invisible.

I spent several days debugging why a fully functional custom stdio MCP server wouldn't register. The server worked perfectly when tested manually (responded to initialize + tools/list instantly). The issue was purely that the config was in the wrong file.

Related issues: #4976, #3321

Suggested Improvement

Add a warning box near the top of the "Installing MCP servers" section or next to the "Where are MCP servers stored?" note:

Important: mcpServers is only read from ~/.claude.json (user/local scope) and .mcp.json (project scope). Placing mcpServers in ~/.claude/settings.json or ~/.claude/settings.local.json has no effect and produces no error.

Ideally, Claude Code should also log a warning or error if it detects an mcpServers key in settings.json or settings.local.json, since those files are already parsed for other purposes.

Impact

High - Prevents users from using a feature

Additional Context

• Windows 10, Claude Code v2.1.34 (Cursor extension)
• Custom stdio MCP server (Python, JSON-RPC 2.0)
• The server was verified working via manual stdin/stdout testing
• Context7 (HTTP MCP) worked fine because it was added via claude mcp add, which writes to ~/.claude.json
• The custom server was manually added to settings.json and settings.local.json — wrong files
• Multiple prior issues report the same confusion: #4976, #3321, #5037