[DOCS] MCP scope-precedence docs omit `/doctor` warning for same-name servers with different endpoints

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

MCP installation scopes → Scope hierarchy and precedence, plus /doctor MCP configuration diagnostics

Current Documentation

The docs currently say:

When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source: 1. Local scope 2. Project scope 3. User scope 4. Plugin-provided servers 5. claude.ai connectors The three scopes match duplicates by name. Plugins and connectors match by endpoint, so one that points at the same URL or command as a server above is treated as a duplicate.

The troubleshooting page also says:

Run /doctor to diagnose issues. It checks: Installation type, version, and search functionality Auto-update status and available versions Invalid settings files (malformed JSON, incorrect types) MCP server configuration errors

What's Wrong or Missing?

Changelog v2.1.110 added a specific /doctor warning for an MCP server that is defined in multiple config scopes with different endpoints.

The current MCP docs explain precedence and duplicate matching by name, but they do not explain an important edge case: the same server name can exist in local, project, or user scope while pointing at different URLs/commands, and Claude Code now warns about that mismatch.

Without that detail, the current wording makes duplicate names sound harmless because Claude Code simply picks the highest-precedence definition. Users are not told that conflicting endpoints across scopes are a configuration problem worth checking with /doctor, especially when moving a server between scopes or reusing one server name for staging vs production.

Suggested Improvement

Add a note under Scope hierarchy and precedence in the MCP docs that says:

• local/project/user MCP servers are deduplicated by server name
• if the same name resolves to different endpoints or commands across scopes, Claude Code uses the highest-precedence definition
• /doctor warns about this mismatch so users can consolidate the server into one scope or rename one of the definitions

Also expand the troubleshooting /doctor checklist with a concrete example such as “conflicting MCP server definitions across scopes (same name, different endpoint)” so users know what kind of MCP problem /doctor can detect.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 439-526 | MCP installation scopes, scope precedence, and duplicate matching by name |
| https://code.claude.com/docs/en/settings | 66-70 | Shows where MCP server definitions live in user, project, and local scopes |
| https://code.claude.com/docs/en/troubleshooting | 968-975 | /doctor checklist mentions only generic “MCP server configuration errors” |
| https://code.claude.com/docs/en/commands | 39 | /doctor command description |

Total scope: 4 pages affected

Source: Changelog v2.1.110

Exact changelog entry text:

Improved /doctor to warn when an MCP server is defined in multiple config scopes with different endpoints