›_ Claude Code Issues
Claude Code Issues / #70704

[DOCS] MCP OAuth docs omit retry-on-transient behavior for discovery and token requests, and omit automatic headless paste-URL fallback

Open 💬 0 comments Opened Jun 25, 2026 by coygeek

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

  • "Authenticate with remote MCP servers" section (around lines 477–512), particularly the <Tip> block at lines 503–511 that summarizes OAuth behavior.
  • "Authenticate from the command line" subsection (around lines 515–527), which currently documents the claude mcp login flow and the manual --no-browser flag for SSH.
  • "Override OAuth metadata discovery" subsection (around lines 613–633), which describes the discovery chain that the new retry behavior protects.
  • The CLI reference table entry for claude mcp login <name> at https://code.claude.com/docs/en/cli-reference (around line 34), which currently attributes paste-URL behavior to the explicit --no-browser flag only.

Current Documentation

The "Authenticate with remote MCP servers" <Tip> block (mcp.md lines 503–511) currently summarizes MCP OAuth behavior as:

Authentication tokens are stored securely and refreshed automatically Use "Clear authentication" in the /mcp menu to revoke access If your browser doesn't open automatically, copy the provided URL and open it manually If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code * OAuth authentication works with HTTP servers

The "Authenticate from the command line" subsection (mcp.md lines 515–527) describes only the manual SSH workaround:

From v2.1.186, claude mcp login <name> runs a configured server's OAuth flow directly from your shell, so you don't need to open the /mcp panel inside a session. ``bash claude mcp login sentry ` To clear stored credentials later, run claude mcp logout <name>. When you're connected over SSH, add --no-browser so the command prints the authorization URL instead of opening a browser. Open the URL on your local machine, then paste the full redirect URL from your browser's address bar back at the prompt. The command needs an interactive terminal for the paste step, so connect with ssh -t. `bash claude mcp login sentry --no-browser ``

The CLI reference (cli-reference.md line 34) likewise attributes the paste-the-URL flow to the explicit flag:

claude mcp login <name> | Run a configured MCP server's OAuth flow without opening the interactive /mcp panel. Works for HTTP, SSE, and claude.ai connector servers. Add --no-browser over SSH to print the authorization URL instead of opening a browser, then paste the redirect URL back at the prompt. Requires Claude Code v2.1.186 or later.

The "Override OAuth metadata discovery" subsection (mcp.md lines 613–633) documents the discovery chain but says nothing about retry behavior:

Point Claude Code at a specific OAuth authorization server metadata URL to bypass the default discovery chain. Set authServerMetadataUrl when the MCP server's standard endpoints error, or when you want to route discovery through an internal proxy. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource, then falls back to RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server.

The "Automatic reconnection" section (mcp.md lines 175–177) describes retry semantics for the MCP transport connection only, not for OAuth discovery or token requests:

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.

What's Wrong or Missing?

The Claude Code v2.1.191 changelog ships two MCP OAuth reliability improvements that the documentation does not yet reflect.

A. No documentation of retry-on-transient behavior for OAuth discovery and token requests

v2.1.191 makes the OAuth discovery chain (RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource, then RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server) and the OAuth token endpoint requests (token exchange and token refresh) retry once on transient network errors. None of the four locations above describe this retry path:

  • The <Tip> block at line 503 says tokens are "refreshed automatically" but does not distinguish refresh from the initial discovery and token exchange, and does not describe any retry behavior on transient errors during those HTTP calls.
  • The "Override OAuth metadata discovery" section at line 613 documents the discovery chain but says nothing about retry semantics if a /.well-known lookup fails with a transient error.
  • The "Automatic reconnection" section at line 175 explicitly carves OAuth out of its scope ("Authentication and not-found errors are not retried because they require a configuration change to resolve"), which is now misleading because the v2.1.191 retry behavior covers OAuth discovery and token HTTP requests, just not the underlying authentication-decision errors.
  • The CLI reference at cli-reference.md line 34 makes no mention of OAuth HTTP retry semantics.

A reader cannot tell from the docs whether a flaky /.well-known lookup, dynamic client registration, or token endpoint call will be retried or whether it will surface as a hard failure to the user.

B. No documentation that headless environments automatically skip the browser popup

v2.1.191 makes Claude Code detect headless environments and skip the browser popup entirely, going straight to the paste-the-URL prompt that was previously only reachable via the explicit --no-browser flag (used for SSH). The current docs frame paste-the-URL as a manual SSH-only workaround:

  • The mcp.md "Authenticate from the command line" subsection at lines 522–527 attributes paste-URL exclusively to the user supplying --no-browser over SSH.
  • The CLI reference at cli-reference.md line 34 likewise attributes paste-URL to the --no-browser flag.

A user running Claude Code in a headless environment (CI, container, devcontainer, agent SDK, server) cannot learn from the docs that the paste-URL flow now happens automatically. They would still believe they must add --no-browser manually, which is unnecessary in v2.1.191 and now redundant in environments Claude Code already detects as headless.

C. No version-stamped mention tying this behavior to v2.1.191

The docs use From v2.1.186, As of v2.1.121, As of v2.1.121, etc. to mark when behavior changed. There is no such marker for the v2.1.191 retry or headless detection, so readers comparing pre-2.1.191 guidance to the running CLI have no signal that the OAuth flow now behaves differently.

Suggested Improvement

Augment the existing MCP OAuth documentation in https://code.claude.com/docs/en/mcp (with a one-line update to https://code.claude.com/docs/en/cli-reference) to cover both v2.1.191 changes.

A. Document retry-on-transient for OAuth discovery and token requests

Expand the <Tip> block at lines 503–511 to add a bullet for the new retry behavior, for example:

* OAuth discovery (RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource and RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server) and OAuth token endpoint requests retry once on transient network errors. This retry covers HTTP-level failures during discovery, dynamic client registration, and token exchange; it does not retry on 4xx responses that indicate an actual configuration or scope problem.

Also amend the "Automatic reconnection" section at line 175 to clarify that the v2.1.191 OAuth retry is a separate, narrower retry path that operates on the OAuth HTTP requests themselves rather than on the MCP transport connection:

The OAuth discovery and token endpoint requests added in v2.1.191 retry once on transient network errors. This is a separate retry path from the connection-level retries described above.

B. Document automatic headless paste-URL fallback

Update the "Authenticate from the command line" subsection at lines 515–527 to introduce the headless detection and explain how it interacts with --no-browser:

From v2.1.186, claude mcp login <name> runs a configured server's OAuth flow directly from your shell, so you don't need to open the /mcp panel inside a session. ``bash claude mcp login sentry ` To clear stored credentials later, run claude mcp logout <name>. **Headless environments.** As of v2.1.191, Claude Code detects headless environments (CI runners, containers, devcontainers, agent SDK runs) and skips the browser popup automatically, going straight to the paste-the-URL prompt. Add --no-browser only when you want to force this behavior in an environment Claude Code does not detect as headless, such as an SSH session to a remote shell. `bash # Force paste-the-URL flow over SSH claude mcp login sentry --no-browser ``

Mirror this change in the CLI reference table at https://code.claude.com/docs/en/cli-reference (around line 34), for example:

claude mcp login <name> | Run a configured MCP server's OAuth flow without opening the interactive /mcp panel. Works for HTTP, SSE, and claude.ai connector servers. As of v2.1.191, headless environments automatically skip the browser popup and go straight to the paste-the-URL prompt. Add --no-browser to force the paste-the-URL flow in environments Claude Code does not detect as headless, such as SSH.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 175–177 | "Automatic reconnection" only covers transport-level retries; the new OAuth-discovery/token-request retry is not mentioned |
| https://code.claude.com/docs/en/mcp | 503–511 | <Tip> block summarizes OAuth behavior but says nothing about transient retry semantics |
| https://code.claude.com/docs/en/mcp | 515–527 | "Authenticate from the command line" attributes paste-the-URL to manual --no-browser over SSH only |
| https://code.claude.com/docs/en/mcp | 613–633 | "Override OAuth metadata discovery" documents the discovery chain but not its retry behavior |
| https://code.claude.com/docs/en/cli-reference | 34 | claude mcp login row attributes paste-the-URL to --no-browser and lacks any mention of automatic headless detection |

Total scope: 1 primary page (https://code.claude.com/docs/en/mcp) plus 1 cross-reference page (https://code.claude.com/docs/en/cli-reference).

Changelog version: v2.1.191

Exact changelog entry:

Improved MCP OAuth: discovery and token requests now retry once after transient network errors, and headless environments skip the browser popup and go straight to the paste-the-URL prompt

Related but distinct doc gaps already filed (not duplicates of this one):

  • Connection-level transient retry behavior was documented in v2.1.121 ("Automatic reconnection" section, mcp.md lines 173–177).
  • Mid-session reconnect exponential backoff is documented in the same section.
  • The /mcp "needs auth" vs "failed" status distinction for claude.ai connectors (separate issue) is about status display, not OAuth HTTP retry semantics.
  • Proxy/mTLS environment-variable compatibility for the OAuth flow (separate issue) covers network-config, not retry-on-transient.
  • Re-authentication after MCP refresh-token expiry (separate issue) covers the recovery prompt, not discovery/token-request HTTP retry.
  • Capability discovery (tools/list, prompts/list, resources/list) retry with backoff added in v2.1.191 (a separately filed issue in this same release) is a parallel retry path for the MCP capability surface; this issue is scoped specifically to the OAuth discovery and token-request HTTP retry plus headless paste-URL detection added in the same changelog line.

This issue is scoped to the v2.1.191 MCP OAuth discovery/token-request retry and headless auto-paste behavior, which are distinct from the MCP capability-discovery retry filed separately.

View original on GitHub ↗