claude-code - 💡(How to fix) Fix [DOCS] MCP docs only describe `needs auth` for 401 responses, not 403-on-connect HTTP/SSE servers [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Automatic reconnection and Authenticate with remote MCP servers, especially the /mcp status behavior for remote HTTP/SSE servers during initial connect

Current Documentation

The docs currently say:

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.

Claude Code marks a remote server as needing authentication when the server responds with 401 Unauthorized and a WWW-Authenticate header pointing to its authorization server. Any custom server that returns that response gets the same /mcp authentication flow as any other remote server.

If the server later returns a 403 insufficient_scope for a tool call, Claude Code re-authenticates with the same pinned scopes.

What's Wrong or Missing?

A. The needs auth explanation is narrower than current behavior

The page currently documents needs auth only for remote servers that respond with 401 Unauthorized plus WWW-Authenticate.

However, the v2.1.141 changelog says Claude Code now treats MCP HTTP/SSE servers that return 403 on initial connect as needs auth instead of failed. The current page does not mention that connect-time 403 case anywhere.

B. The startup failure text still reads as if those servers only end up in failed

The Automatic reconnection section explains when startup failures are retried and says a server is marked as failed if it still cannot connect, but it does not clarify that auth-required HTTP/SSE servers returning 403 during connect now surface as needs auth rather than failed.

Suggested Improvement

Add one explicit note in the remote-authentication section and one cross-reference in the startup-failure section. For example:

Claude Code marks a remote server as needing authentication when the initial connect response indicates user authentication is required. This includes 401 Unauthorized responses with WWW-Authenticate, and as of v2.1.141 also includes HTTP/SSE servers that return 403 during connect for an auth-required session.

And in the startup behavior section:

Auth-required connect errors do not always appear as failed. If a remote HTTP/SSE server returns an authentication-related 403 during initial connect, Claude Code shows needs auth in /mcp so you can authenticate and retry.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Version note: The v2.1.141 release entry says: Fixed MCP HTTP/SSE servers returning 403 on connect showing as "failed" instead of "needs auth".