[DOCS] [MCP] Document "needs auth" vs "failed" status distinction and non-transient 4xx retry behavior in headless mode

Documentation Type

Other — documentation gap: specific behavioral edge cases not documented

Documentation Location

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

Section/Topic

• "Server shows 'failed' status" / MCP connection status display
• "Automatic reconnection" subsection (lines 338–343)
• Headless mode (-p) retry behavior (cross-reference from https://code.claude.com/docs/en/headless)

Current Documentation

Status values are defined in the Agent SDK docs (agent-sdk/typescript.md line 2349):

status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";

Automatic reconnection section (mcp.md lines 338–343) currently says:

If 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.

Headless mode documentation (headless.md lines 153–165) documents system/api_retry events with error_status and error fields but does not specify which HTTP status codes constitute transient vs non-transient failures.

What's Wrong or Missing?

A. "needs-auth" vs "failed" status distinction not documented

The documentation defines the five MCP server status values but does not explain when each applies, specifically:

• What causes a server to show "needs-auth" instead of "failed"?
• How should users interpret and respond to "needs-auth" vs "failed"?
• The changelog for v2.1.132 fixes a bug where unauthorized claude.ai MCP connectors showed "failed" instead of "needs auth", but no docs explain this distinction.

A claude.ai MCP connector that has not completed OAuth authentication should display as "needs auth", not "failed". Users seeing "failed" may not know to complete the OAuth flow via /mcp.

B. Non-transient 4xx retry behavior in headless -p mode not documented

The mcp.md "Automatic reconnection" section explicitly states which errors are not retried:

Authentication and not-found errors are not retried because they require a configuration change to resolve.

However:

1. The docs do not explain the broader category of non-transient 4xx connection failures beyond authentication and not-found cases
2. The headless mode (-p) documentation does not cross-reference MCP retry behavior or clarify that non-transient 4xx failures are not retried
3. The distinction between headless mode retry behavior and MCP connection retry behavior is not explained

As of v2.1.132, -p mode no longer retries non-transient 4xx connection failures (it previously did, which was a bug). This behavioral change is not reflected in the docs.

Suggested Improvement

For section "Automatic reconnection" in mcp.md

Expand the retry/not-retry list to cover the broader non-transient 4xx case:

Claude Code retries the initial connection up to three times on transient errors such as a 5xx response, a connection refused, or a timeout. Authentication errors, not-found errors, and other non-transient 4xx responses are not retried because they require a configuration change to resolve. After three failed attempts the server is marked as failed and you can retry manually from /mcp.

Add a cross-reference note:

For headless (-p) mode, these same non-transient 4xx errors are not retried at the API level — see headless mode retry behavior for details.

For agent-sdk/mcp.md "Server shows 'failed' status" section

Clarify the distinction between "needs-auth" and "failed":

"needs-auth" vs "failed": If a server shows "failed" status, it encountered a connection error (network issue, timeout, server unreachable). If a server shows "needs-auth", it reached the server but requires authentication (OAuth or credentials). For MCP connectors from claude.ai (Slack, Gmail, etc.), "needs-auth" means the OAuth flow has not been completed — run /mcp to authenticate. A server showing "failed" may become "needs-auth" after the user resolves the auth issue.

For headless.md

In the system/api_retry event table, add a note:

Non-transient 4xx errors are not retried. Retry behavior is reserved for transient failures such as 5xx responses, connection failures, and timeouts. For MCP server connection retry behavior, see MCP documentation.

Impact

Medium - Makes feature difficult to understand correctly

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 338–343 | "Automatic reconnection" — retry behavior list incomplete |
| https://code.claude.com/docs/en/agent-sdk/mcp | 718–730 | "Server shows 'failed' status" — doesn't distinguish from "needs-auth" |
| https://code.claude.com/docs/en/headless | 153–165 | system/api_retry event table — no 4xx non-transient note |

Total scope: 3 pages affected

Version context: The distinction between "failed" and "needs auth" for claude.ai MCP connectors and the non-transient 4xx retry behavior were both fixed in v2.1.132. The docs do not yet reflect the corrected behavior.