Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP scope-precedence docs omit `/doctor` warning for same-name servers with different endpoints [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#48857•Fetched 2026-04-16 06:49:03
View on GitHub
Comments
1
Participants
2
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeekgithub-actions[bot]github-actions[bot]
Timeline (top)
labeled ×3commented ×1

Error Message

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

Root Cause

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.

RAW_BUFFERClick to expand / collapse

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:

PageLine(s)Context
https://code.claude.com/docs/en/mcp439-526MCP installation scopes, scope precedence, and duplicate matching by name
https://code.claude.com/docs/en/settings66-70Shows where MCP server definitions live in user, project, and local scopes
https://code.claude.com/docs/en/troubleshooting968-975/doctor checklist mentions only generic “MCP server configuration errors”
https://code.claude.com/docs/en/commands39/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

extent analysis

TL;DR

Update the MCP documentation to include a note about the potential issue of duplicate server names with different endpoints across scopes and expand the /doctor troubleshooting checklist with a concrete example.

Guidance

  • Add a note under Scope hierarchy and precedence in the MCP docs to explain that local/project/user MCP servers are deduplicated by server name, but if the same name resolves to different endpoints or commands across scopes, Claude Code uses the highest-precedence definition.
  • Expand the troubleshooting /doctor checklist to include a concrete example of "conflicting MCP server definitions across scopes (same name, different endpoint)".
  • Review the affected pages (MCP installation scopes, settings, troubleshooting, and commands) to ensure consistency in documentation.
  • Consider adding a warning or example in the changelog entry for v2.1.110 to highlight the importance of this update.

Example

No code snippet is necessary for this documentation update, but an example of the updated note could be: "Note: If the same server name is used in multiple scopes with different endpoints, Claude Code will use the highest-precedence definition. Run /doctor to detect and resolve any conflicts."

Notes

This update is specific to the MCP documentation and does not require any code changes. The goal is to improve the clarity and accuracy of the documentation to help users understand the potential issue and how to resolve it.

Recommendation

Apply workaround: Update the MCP documentation to include the necessary notes and examples to clarify the potential issue and provide guidance on how to resolve it. This will improve the user experience and reduce confusion around duplicate server names with different endpoints across scopes.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#installation#callback error#memory management#API rate limit#configuration error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP scope-precedence docs omit `/doctor` warning for same-name servers with different endpoints [1 comments, 2 participants]