Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP docs don't explain `/mcp` reconnect flow for `headersHelper` and custom-header auth recovery [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52200•Fetched 2026-04-23 07:33:54
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4
RAW_BUFFERClick to expand / collapse

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:

PageContext
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

extent analysis

TL;DR

Update the documentation at https://code.claude.com/docs/en/mcp to include information on how /mcp handles custom authentication headers and recovery from transient auth failures.

Guidance

  • Add a subsection near Use dynamic headers for custom authentication to explain that headersHelper and other custom-header setups are not OAuth flows and use Reconnect to retry the connection.
  • Update the /mcp command summary to mention reconnecting and recovering MCP server connections, not only OAuth authentication.
  • Clarify that OAuth-only actions such as Authenticate, Re-authenticate, and Clear authentication apply to OAuth-backed servers, not headersHelper-based custom auth.
  • Ensure the documentation covers recovery steps for transient auth failures on custom-header HTTP/SSE servers.

Example

No code snippet is necessary for this issue, as it is related to documentation updates.

Notes

The suggested improvements should be applied to the affected pages, including https://code.claude.com/docs/en/mcp and https://code.claude.com/docs/en/commands, to ensure consistency and completeness of the documentation.

Recommendation

Apply the suggested documentation updates to provide clear guidance on using /mcp with custom authentication headers and recovering from transient auth failures, as this will improve the usability of the feature and reduce confusion for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP docs don't explain `/mcp` reconnect flow for `headersHelper` and custom-header auth recovery [1 participants]