[DOCS] MCP docs missing deduplication and precedence rules when local config overlaps Claude.ai connectors

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Scope hierarchy and precedence" and "Use MCP servers from Claude.ai"

Current Documentation

The docs currently say:

MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.

And later on the same page:

If you've logged into Claude Code with a Claude.ai account, MCP servers you've added in Claude.ai are automatically available in Claude Code:

Claude.ai servers appear in the list with indicators showing they come from Claude.ai.

There is no documentation explaining what happens when the same MCP server is configured both locally and via a Claude.ai connector.

What's Wrong or Missing?

Claude Code v2.1.84 added a new conflict-resolution behavior: MCP servers configured both locally and via Claude.ai connectors are now deduplicated, and the local configuration wins.

The current MCP docs describe local/project/user precedence and Claude.ai connector availability separately, but they do not document their interaction. Users cannot tell:

1. That overlapping local and Claude.ai MCP server definitions collapse to a single effective server instead of producing duplicate entries/tools.
2. That the local configuration takes precedence over the Claude.ai connector when both exist.
3. Why a Claude.ai connector may not appear as a separate server in /mcp when a local definition already exists.

Suggested Improvement

Add a note to the MCP page near either the precedence section or the Claude.ai connectors section explaining the overlap case explicitly. Suggested content outline:

If the same MCP server is configured both locally and via Claude.ai connectors, Claude Code deduplicates the entries and uses the local configuration.

Also clarify:

• how Claude Code determines that two definitions are duplicates,
• what users should expect to see in /mcp, and
• that this behavior was introduced in v2.1.84.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Documents scope precedence and Claude.ai MCP server availability, but not deduplication/precedence when both define the same server |

Total scope: 1 page affected

Source: Changelog v2.1.84

Exact changelog entry:

MCP servers configured both locally and via claude.ai connectors are now deduplicated — the local config wins