[DOCS] MCP docs missing startup auto-retry behavior for transient errors

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Managing your servers, Automatic reconnection, and MCP server startup connection behavior

Current Documentation

The docs currently say:

If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts, starting at a one-second delay and doubling each time. The server appears as pending in /mcp while reconnection is in progress. After five failed attempts the server is marked as failed and you can retry manually from /mcp. Stdio servers are local processes and are not reconnected automatically.

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

And the error guide currently sends MCP connection failures back to the MCP page:

* MCP server failed to connect or authenticate: MCP

No documentation currently explains what Claude Code does when an MCP server hits a transient error during startup.

What's Wrong or Missing?

Changelog v2.1.121 added this behavior:

MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected

The current MCP docs describe mid-session HTTP/SSE reconnection, manual reconnect via /mcp, and startup connection behavior for enabled servers, but they do not document:

• that transient startup failures are retried automatically
• the startup retry limit of up to 3 attempts
• how startup retries differ from the existing mid-session reconnection flow

That leaves a user-visible MCP connection behavior documented only in the changelog.

Suggested Improvement

Add a short startup retry note to the MCP docs near the existing reconnection/startup lifecycle sections that explains:

• transient MCP startup errors are retried automatically
• Claude Code retries up to 3 times during startup
• this startup behavior is separate from the existing mid-session HTTP/SSE reconnection behavior
• what users should do in /mcp if the server still fails after the startup retries are exhausted

Also add a brief troubleshooting cross-reference from the MCP failure guidance so users checking connection/authentication failures know startup retries may already have been attempted.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary documentation for MCP lifecycle, startup connection, automatic reconnection, and /mcp management |
| https://code.claude.com/docs/en/errors | Sends users with MCP connection/authentication failures to the MCP docs |

Total scope: 2 pages affected

Source: Changelog v2.1.121

Exact changelog entry:

MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected