Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP OAuth docs omit step-up authorization re-authorization behavior [1 comments, 2 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#52201•Fetched 2026-04-23 07:33:53
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeekgithub-actions[bot]github-actions[bot]
Timeline (top)
labeled ×4commented ×1

Error Message

  • 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
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Authenticate with remote MCP servers

Current Documentation

The docs currently say:

Many cloud-based MCP servers require authentication. Claude Code supports OAuth 2.0 for secure connections.

  • 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 same page later says:

Run /mcp in Claude Code and follow the browser login flow.

There is no documentation for step-up authorization when a remote MCP server later requests elevated scopes.

What's Wrong or Missing?

Changelog v2.1.118 includes a fix for MCP step-up authorization when a server returns 403 insufficient_scope and Claude Code needs to trigger re-authorization instead of silently refreshing the existing token.

The current MCP docs only describe the initial OAuth login flow and automatic token refresh. They do not explain that:

  • a remote MCP server can reject an otherwise valid token with 403 insufficient_scope
  • that response can mean the server is requesting elevated scopes or renewed consent
  • Claude Code may need to prompt the user through the browser re-authorization flow again instead of silently refreshing

Without that explanation, users and MCP server operators have no documentation for this user-visible auth path or how it differs from ordinary token refresh.

Suggested Improvement

Add a short subsection under Authenticate with remote MCP servers, such as Step-up authorization and elevated scopes, that explains:

  1. Some remote MCP servers may return 403 insufficient_scope after initial setup when a tool or resource requires additional scopes.
  2. In that case, Claude Code can trigger the browser re-authorization flow to request the additional consent instead of only refreshing the current token.
  3. Users should complete the new browser consent flow from /mcp, and can use Clear authentication if they need to restart the OAuth session.

This section does not need a long example, but it should document the expected behavior so users understand why a previously connected MCP server may ask for consent again.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/mcpPrimary Claude Code documentation for remote MCP OAuth authentication

Total scope: 1 page affected

Source: Changelog v2.1.118

Exact changelog entry:

Fixed MCP step-up authorization silently refreshing instead of prompting for re-consent when the server's insufficient_scope 403 names a scope the current token already has

extent analysis

TL;DR

Add documentation for step-up authorization and elevated scopes to the Authenticate with remote MCP servers section.

Guidance

  • Identify the missing documentation: The current documentation only describes the initial OAuth login flow and automatic token refresh, but does not explain step-up authorization when a remote MCP server requests elevated scopes.
  • Determine the required changes: Add a subsection under Authenticate with remote MCP servers to explain step-up authorization, including the possibility of 403 insufficient_scope responses and the need for users to complete a new browser consent flow.
  • Verify the fix: Check that the updated documentation clearly explains the expected behavior for step-up authorization and elevated scopes, and that users can understand why a previously connected MCP server may ask for consent again.
  • Review affected pages: Ensure that the changes are applied to the primary Claude Code documentation for remote MCP OAuth authentication, which is the only affected page.

Example

No code snippet is necessary for this issue, as it is related to documentation rather than code changes.

Notes

The suggested improvement is to add a short subsection to the existing documentation, which should be a relatively straightforward change. However, it is essential to ensure that the new documentation is accurate and clear to avoid confusing users.

Recommendation

Apply workaround: Add the suggested documentation subsection to explain step-up authorization and elevated scopes, as this will provide users with the necessary information to understand the expected behavior and resolve the issue.

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#request timeout

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 OAuth docs omit step-up authorization re-authorization behavior [1 comments, 2 participants]