claude-code - 💡(How to fix) Fix [DOCS] [MCP] Document retry behavior and `/mcp` status for servers that connect but fail `tools/list` [1 participants]

Documentation Type

other

Documentation Location

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

Section/Topic

"Automatic reconnection" section or a new subsection covering server lifecycle and tool-list failures

Current Documentation

The "Automatic reconnection" section (lines 338–342) documents:

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 /mcp panel section (line 330) notes:

The /mcp panel shows the tool count next to each connected server and flags servers that advertise the tools capability but expose no tools.

The debug-your-config page (line 52) describes the zero-tools symptom:

A server that shows as connected but lists zero tools has started successfully but isn't returning a tool list. Select Reconnect from /mcp. If the count stays at zero, run claude --debug mcp to see the server's stderr output.

What's Wrong or Missing?

The docs do not cover the scenario where an MCP server successfully connects (TCP connection succeeds) but the tools/list call fails. In this case:

1. Previous behavior (undocumented): The server appeared connected in /mcp but silently showed 0 tools with no explanation or retry.
2. Current behavior (undocumented as of v2.1.132): Claude Code retries the tools/list call once. If it still fails, the server shows "connected · tools fetch failed" in /mcp instead of silently displaying 0 tools.

This is distinct from connection failures (covered by the v2.1.121 retry docs) and mid-session disconnections (covered by the reconnect docs). The /mcp panel has no documented status for this specific failure mode, and the retry-once behavior for tools/list failures is not mentioned anywhere.

Users encountering this see a cryptic "connected · tools fetch failed" status with no documentation to explain what it means or how to resolve it.

Suggested Improvement

Add documentation in the MCP reference covering:

A new "Tool list failures" subsection under the "Automatic reconnection" section or a standalone "Server status and failures" section:

### Tool list failures

A server may successfully establish a connection but fail to return a tool list from its `tools/list` handler. This differs from connection failures (which use the connection retry logic) and from mid-session disconnections (which use the reconnect backoff).

When a `tools/list` call fails on an otherwise-connected server, Claude Code retries the call once. If the retry also fails, the server displays "connected · tools fetch failed" in `/mcp` instead of silently showing zero tools. This status indicates the server is reachable but its tool handler returned an error or timed out.

To diagnose a "connected · tools fetch failed" status:
1. Select **Reconnect** from `/mcp` to trigger another `tools/list` attempt.
2. If the issue persists, run `claude --debug mcp` to view the server's stderr output for error details.
3. Check the server's `tools/list` handler for errors, timeouts, or incorrect response schema.

Also update the /mcp panel description (line 330) to mention the "tools fetch failed" status alongside the existing zero-tools flag.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog entry (v2.1.132): "Fixed MCP servers that connect but fail tools/list silently showing 0 tools — they now retry once and show 'connected · tools fetch failed' in /mcp"

Existing related docs:

• https://code.claude.com/docs/en/mcp (line 330: /mcp panel tool count display)
• https://code.claude.com/docs/en/mcp (lines 338–342: automatic reconnection for connection failures)
• https://code.claude.com/docs/en/debug-your-config (line 52: zero-tools troubleshooting)