[DOCS] MCP docs missing plugin-provided server deduplication behavior

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Plugin-provided MCP servers" section

Current Documentation

mcp.md documents plugin-provided MCP servers:

"Plugin MCP servers work identically to user-configured servers."
"Plugin servers are managed through plugin installation (not /mcp commands)"

plugins-reference.md documents MCP server configuration syntax and lifecycle:

"Plugin MCP servers start automatically when the plugin is enabled"
"Servers appear as standard MCP tools in Claude's toolkit"

Neither page mentions any deduplication behavior between plugin-provided and manually-configured MCP servers.

What's Wrong or Missing?

Changelog v2.1.71 introduces a deduplication rule for plugin-provided MCP servers:

"Improved plugin-provided MCP server deduplication — servers that duplicate a manually-configured server (same command/URL) are now skipped, preventing duplicate connections and tool sets. Suppressions are shown in the /plugin menu."

This behavior is entirely undocumented. Users who have both a manually-configured MCP server and a plugin that provides the same server (same command or URL) will see the plugin's copy silently skipped. Without documentation, this can appear as a plugin malfunction.

Specifically missing:

1. The deduplication rule: if a plugin-provided MCP server has the same command or URL as a manually-configured server, it is skipped.
2. Where to see which servers were suppressed: the /plugin menu shows suppressions.
3. User guidance on what to do if they want the plugin version instead of the manual one (presumably: remove the manual configuration).

Suggested Improvement

Add a "Deduplication" note to the "Plugin-provided MCP servers" section in mcp.md:

Deduplication: If a plugin provides an MCP server with the same command or URL as a manually-configured server, the plugin's server is skipped automatically to prevent duplicate connections and tool sets. Suppressed servers are listed in the /plugin menu. To use the plugin's server instead, remove the matching entry from your manual MCP configuration.

Add a corresponding note in plugins-reference.md under the MCP servers section.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/mcp	"Plugin-provided MCP servers" section — deduplication behavior absent
https://code.claude.com/docs/en/plugins-reference	MCP server lifecycle section — deduplication behavior absent

Total scope: 2 pages affected

Source: Changelog v2.1.71

Exact changelog entry:

"Improved plugin-provided MCP server deduplication — servers that duplicate a manually-configured server (same command/URL) are now skipped, preventing duplicate connections and tool sets. Suppressions are shown in the /plugin menu."

[coygeek]

Still unresolved as of 2026-03-28 after re-checking the current docs. The documentation gap described in this issue is still present.

[coygeek]

Quickly checked the latest docs again. Parts of this issue may be improved, but it is still not fully resolved, so it should stay open.

[coygeek]

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.