[DOCS] Plugin MCP lifecycle docs omit connection preservation during mid-session server resync

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The Plugin-provided MCP servers section, especially Automatic lifecycle, and the related /reload-plugins guidance.

Current Documentation

The MCP reference currently says:

Plugin MCP servers work identically to user-configured servers.

Under Plugin MCP features, it says:

Automatic lifecycle: at session startup, servers for enabled plugins connect automatically. If you enable or disable a plugin during a session, run /reload-plugins to connect or disconnect its MCP servers

The plugin guide also says:

Claude Code reloads all active plugins and shows counts for plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers.

What's Wrong or Missing?

Claude Code v2.1.210 fixed plugin-provided MCP servers being torn down when MCP servers are re-synced during an active session. The current documentation explains startup connection and the intentional connect/disconnect behavior for enabling or disabling a plugin, but it does not explain what happens to an already connected plugin MCP server during a mid-session MCP re-sync.

This leaves plugin authors and users without a documented expectation that an unrelated server re-sync should preserve active plugin-provided MCP connections. If a plugin's tools disappear during a refresh, the docs also do not explain whether the user should wait, run /reload-plugins, or inspect the server in /mcp.

Suggested Improvement

Add a lifecycle note to the MCP reference and cross-reference it from the /reload-plugins guidance. For example:

As of Claude Code v2.1.210, re-synchronizing MCP servers during a session does not tear down already connected plugin-provided MCP servers. Enabling or disabling a plugin, or explicitly reloading plugin components with /reload-plugins, can still intentionally connect, disconnect, or replace the affected plugin's servers. Use /mcp to check the connection status if a plugin's tools are unavailable.

Define what triggers an MCP re-sync and distinguish that operation from an explicit plugin reload, so users know which changes preserve existing connections and which changes restart them.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 230-239, 273-280 | Plugin MCP server lifecycle and connection management |
| https://code.claude.com/docs/en/discover-plugins | 359-369 | Applying plugin changes with /reload-plugins |
| https://code.claude.com/docs/en/plugins-reference | 691-695 | Plugin updates and MCP server paths during an active session |

Total scope: 3 pages affected

The behavior change is documented in Claude Code v2.1.210. The existing prompt-caching guidance explains the cache effects of MCP connections and plugin changes, but it does not document the connection-preservation guarantee for plugin-provided MCP servers during a re-sync: https://code.claude.com/docs/en/prompt-caching