[DOCS] MCP docs omit plugin-provided server deduplication with Claude.ai connectors

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Plugin-provided MCP servers, Scope hierarchy and precedence, and Use MCP servers from Claude.ai

Current Documentation

The MCP docs currently say:

Plugins can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers. When a plugin is enabled, its MCP servers start automatically Plugin MCP tools appear alongside manually configured MCP tools

The same page currently documents one precedence rule for connectors:

If a server is configured both locally and through a [claude.ai connector](#use-mcp-servers-from-claude-ai), the local configuration takes precedence and the connector entry is skipped.

The Claude.ai connector section says:

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:

Later in the same section it says:

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

The plugin reference also says:

Plugin MCP servers start automatically when the plugin is enabled Servers appear as standard MCP tools in Claude's toolkit * Plugin servers can be configured independently of user MCP servers

What's Wrong or Missing?

Release notes for v2.1.92 fixed a case where plugin MCP servers could get stuck on "connecting" at session start when they duplicated an unauthenticated Claude.ai connector.

Current docs explain plugin MCP servers and Claude.ai connectors separately, and they explain local-vs-connector precedence, but they do not explain the plugin-vs-connector overlap case at all.

Missing guidance includes:

• whether duplicate plugin/connector pairs are deduplicated instead of opening two connections
• which entry remains active and which one is suppressed when a plugin-provided MCP server duplicates a Claude.ai connector
• whether the same duplicate-resolution rule applies when the Claude.ai connector exists but is not yet authenticated
• where users should look in the UI to understand why a plugin-provided MCP server did not connect separately

Without that documentation, plugin authors and end users cannot predict whether overlapping plugin servers and Claude.ai connectors will both appear, be merged, or be suppressed, which makes startup and connection behavior hard to reason about.

Suggested Improvement

Add a short duplicate-resolution subsection to https://code.claude.com/docs/en/mcp, near the existing plugin and Claude.ai connector sections.

Document:

• how Claude Code resolves duplicate MCP definitions across local/project/user config, plugins, and Claude.ai connectors
• the specific behavior when a plugin-provided server duplicates a Claude.ai connector
• whether an unauthenticated connector still participates in deduplication
• where Claude Code surfaces the active/suppressed entry in the UI

Then add a cross-reference from https://code.claude.com/docs/en/plugins-reference so plugin authors know what to expect when bundling servers that overlap with connectors users may already have configured in Claude.ai.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 360-417 | Plugin-provided MCP server lifecycle and visibility |
| https://code.claude.com/docs/en/mcp | 497-501 | Only local-vs-Claude.ai connector precedence is documented |
| https://code.claude.com/docs/en/mcp | 892-916 | Claude.ai connector availability and authentication flow |
| https://code.claude.com/docs/en/plugins-reference | 149-181 | Plugin reference says plugin MCP servers start automatically and can be configured independently of user MCP servers |

Total scope: 2 pages affected

No current code.claude.com page explains what happens when a plugin-provided MCP server duplicates a Claude.ai connector, including the unauthenticated-connector case.

Source: Changelog v2.1.92

Changelog entry:

Fixed plugin MCP servers stuck "connecting" on session start when they duplicate a claude.ai connector that is unauthenticated