[DOCS] Plugin MCP deduplication docs imply same-command servers are always duplicates

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Scope hierarchy and precedence" duplicate-matching rules for plugin-provided MCP servers

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. The entire server entry from that source is used; fields are not merged across scopes. 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.

What's Wrong or Missing?

This wording reads as if plugin-provided MCP servers are intentionally deduplicated whenever they share the same command, even if their env blocks differ.

That is outdated as of v2.1.152. The changelog for v2.1.152 says Claude Code fixed plugin MCP servers with the same command but different environment variables being incorrectly deduplicated. In other words, the current mcp page describes the old buggy behavior as if it were the intended rule.

As written, plugin authors can reasonably conclude that only one same-command server will survive even when different environment variables are used to configure distinct server instances.

Suggested Improvement

Update the duplicate-matching sentence so it does not imply that matching the same command is always sufficient to suppress a plugin MCP server.

For example:

Before:

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.

After:

Plugins and connectors are not duplicates solely because they use the same command. For plugin MCP servers, definitions that use different environment variables should be treated as distinct servers.

If there are other fields that affect identity besides env, the page should name them explicitly or avoid overspecifying the matching rule.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 324-335 | Duplicate matching rules in "Scope hierarchy and precedence" |

Total scope: 1 page affected

Version context: v2.1.152 changelog entry:

Fixed plugin MCP servers with the same command but different environment variables being incorrectly deduplicated