[DOCS] MCP docs don't explain `/mcp` reconnect flow for `headersHelper` and custom-header auth recovery

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Managing your servers, Authenticate with remote MCP servers, and Use dynamic headers for custom authentication

Current Documentation

The docs currently say:

# (within Claude Code) Check server status /mcp

* Use /mcp to authenticate with remote servers that require OAuth 2.0 authentication

And the headersHelper section says:

If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use headersHelper to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers. The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.

The page does not explain how /mcp behaves for remote HTTP/SSE servers that use headersHelper or other custom headers instead of OAuth.

What's Wrong or Missing?

Changelog v2.1.118 describes user-facing /mcp behavior for non-OAuth remote MCP authentication, but the docs only describe /mcp as an OAuth authentication surface.

That leaves two gaps:

A. No documented /mcp action for headersHelper servers

The page explains that headersHelper reruns on reconnect, but it never tells users that /mcp should expose a reconnect-style recovery path for these servers rather than OAuth-specific Authenticate/Re-authenticate actions.

B. No recovery guidance for transient auth failures on custom-header HTTP/SSE servers

The docs explain how to configure custom authentication headers, but not how users should recover when a remote HTTP/SSE MCP server temporarily returns 401 or appears to need authentication again. That makes short-lived-token and internal-SSO setups harder to operate.

Suggested Improvement

Add a short subsection in https://code.claude.com/docs/en/mcp near Use dynamic headers for custom authentication that explains:

1. headersHelper and other custom-header setups are not OAuth flows.
2. In /mcp, these servers use Reconnect to retry the connection and rerun headersHelper.
3. For remote HTTP/SSE servers with short-lived or custom auth headers, reconnect is the recovery step after transient auth failures such as a temporary 401.
4. OAuth-only actions such as Authenticate, Re-authenticate, and Clear authentication apply to OAuth-backed servers, not headersHelper-based custom auth.

It would also help to update the /mcp command summary so it mentions reconnecting and recovering MCP server connections, not only OAuth authentication.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | /mcp server management, OAuth auth flow, and headersHelper custom-auth configuration |
| https://code.claude.com/docs/en/commands | /mcp command summary currently describes the command as managing connections and OAuth authentication |

Total scope: 2 pages affected

Source: Changelog v2.1.118

Exact changelog entry:

Fixed /mcp menu hiding OAuth Authenticate/Re-authenticate actions for servers configured with headersHelper, and HTTP/SSE MCP servers with custom headers being stuck in "needs authentication" after a transient 401