Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP docs missing startup auto-retry behavior for transient errors [1 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#54166•Fetched 2026-04-29 06:34:31
View on GitHub
Comments
1
Participants
1
Timeline
5
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3closed ×1commented ×1

Error Message

And the error guide currently sends MCP connection failures back to the MCP page: No documentation currently explains what Claude Code does when an MCP server hits a transient error during startup.

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

RAW_BUFFERClick to expand / collapse

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:

PageContext
https://code.claude.com/docs/en/mcpPrimary documentation for MCP lifecycle, startup connection, automatic reconnection, and /mcp management
https://code.claude.com/docs/en/errorsSends 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

extent analysis

TL;DR

Update the MCP documentation to include information about automatic retry of transient startup errors.

Guidance

  • Add a note to the MCP docs explaining that transient MCP startup errors are retried automatically up to 3 times.
  • Clarify that this startup behavior is separate from the existing mid-session HTTP/SSE reconnection behavior.
  • Provide guidance on what users should do in /mcp if the server still fails after the startup retries are exhausted.
  • Add a brief troubleshooting cross-reference from the MCP failure guidance to inform users that startup retries may have already been attempted.

Example

No code snippet is necessary for this documentation update.

Notes

The update should be made to the MCP documentation page (https://code.claude.com/docs/en/mcp) and potentially the errors page (https://code.claude.com/docs/en/errors) for cross-referencing.

Recommendation

Apply workaround: Update the documentation to reflect the current behavior of automatic retry of transient startup errors, as this will improve user understanding of the feature.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#model loading#dependency error#configuration error#environment variable#network issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP docs missing startup auto-retry behavior for transient errors [1 comments, 1 participants]