[DOCS] MCP docs omit retry-with-backoff behavior for capability discovery calls (`tools/list`, `prompts/list`, `resources/list`)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Automatic reconnection" section (around lines 173–177) and the broader MCP server lifecycle area covering how Claude Code handles transient failures during initial capability discovery. The "Dynamic tool updates" subsection (around line 169) also mentions capability refresh but does not address retry semantics.

Current Documentation

The relevant section currently reads:

### Automatic reconnection 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. The same backoff applies when an HTTP or SSE server fails its initial connection at startup. As of v2.1.121, Claude Code retries the initial connection up to three times on transient errors such as a 5xx response, a connection refused, or a timeout, then marks the server as failed if it still cannot connect. Authentication and not-found errors are not retried because they require a configuration change to resolve.

The "Dynamic tool updates" section (around line 169) only addresses list_changed notifications:

Claude Code supports MCP list_changed notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a list_changed notification, Claude Code automatically refreshes the available capabilities from that server.

Neither section describes any retry behavior for the actual tools/list, prompts/list, or resources/list RPC calls themselves when those individual discovery requests fail with transient network errors.

What's Wrong or Missing?

Per the Claude Code v2.1.191 changelog, MCP capability discovery was made more reliable: the discovery calls (tools/list, prompts/list, resources/list) now retry transient network errors with short backoff. The current MCP documentation describes two retry paths but not this one:

A. No retry documentation for capability discovery RPCs

The "Automatic reconnection" section only covers:

• Initial connection failures (up to three retries on transient errors, added in v2.1.121)
• Mid-session disconnect/reconnect for HTTP or SSE servers (exponential backoff, up to five attempts)

Neither covers the case where the transport connection succeeds but the tools/list, prompts/list, or resources/list request itself fails transiently (e.g., partial response, dropped packet mid-stream, transient 5xx during the list call). v2.1.191 changes this so those discovery calls now retry with short backoff, but the docs do not mention this.

B. No scope clarification across all three discovery calls

The fix applies to all three capability types — tools/list, prompts/list, and resources/list. The docs do not call out this set explicitly anywhere. Users reading the MCP reference cannot tell whether transient failures during prompt or resource discovery are retried, or whether only the tool list is.

C. No behavior for list_changed refresh path

The "Dynamic tool updates" section explains that list_changed triggers a fresh capability refresh, but says nothing about whether that refresh path also benefits from the new transient-error retry-with-backoff behavior. Readers cannot tell whether a list_changed-driven rediscovery uses the same retry semantics.

Suggested Improvement

Add a new subsection or expand the "Automatic reconnection" section in https://code.claude.com/docs/en/mcp to document capability-discovery retries, for example:

### Capability discovery retries

As of v2.1.191, the MCP capability discovery calls themselves —
`tools/list`, `prompts/list`, and `resources/list` — retry on
transient network errors with short backoff. This applies whether
discovery is happening at session startup or in response to a
`list_changed` notification from the server.

A transient error includes partial responses, dropped connections
mid-response, and 5xx responses returned from the list call itself.
Authentication and not-found errors are not retried, because they
require a configuration change to resolve.

This retry path is separate from the initial-connection retry
(introduced in v2.1.121) and from the mid-session reconnect
exponential backoff for HTTP and SSE servers.

If a fuller description of the backoff schedule (number of attempts, base delay) becomes available later, expand the prose to include those specifics.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 169–171 | "Dynamic tool updates" mentions capability refresh but no retry behavior |
| https://code.claude.com/docs/en/mcp | 173–177 | "Automatic reconnection" covers connection-level retries only |

Total scope: 1 page affected (single section that needs a new or expanded subsection)

Changelog version: v2.1.191 — "Improved MCP server reliability: capability discovery (tools/list, prompts/list, resources/list) now retries transient network errors with short backoff"

Related but distinct doc gaps already filed:

• Connection-level transient retry behavior was documented in v2.1.121 ("Automatic reconnection" section).
• Mid-session reconnect exponential backoff is documented in the same section.
• The /mcp "tools fetch failed" status for already-connected servers that fail tools/list is a separate, narrower retry scenario.

This issue is scoped specifically to the v2.1.191 capability-discovery retry-with-backoff behavior, which spans all three capability types (tools/list, prompts/list, resources/list) and is distinct from the connection-level retry paths already documented.