[DOCS] MCP OAuth docs omit step-up authorization re-authorization behavior

Status Fixed / completed

Maintainer reply None cached

Activity 3 comments · opened Apr 23, 2026 · closed Apr 29, 2026

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:

Some remote MCP servers may return 403 insufficient_scope after initial setup when a tool or resource requires additional scopes.
In that case, Claude Code can trigger the browser re-authorization flow to request the additional consent instead of only refreshing the current token.
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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary 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

View original on GitHub ↗

3 Comments

github-actions[bot] · 5 months ago

Found 1 possible duplicate issue:

https://github.com/anthropics/claude-code/issues/39626

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

coygeek · 5 months ago

Issue #52201 Verification

Title: [DOCS] MCP OAuth docs omit step-up authorization re-authorization behavior
Issue Date: 2026-04-23
Verification Date: 2026-04-28
Status: RESOLVED

---

Issue Summary

This issue reports that the MCP OAuth docs only described the initial browser login flow and token refresh behavior, and omitted the later 403 insufficient_scope re-authorization path for remote MCP servers.

---

Verification Results

Claim 1: The MCP docs omitted that a remote server can later return `403 insufficient_scope` and trigger re-authorization

Status: RESOLVED

At https://code.claude.com/docs/en/mcp, lines 797-801, the page now says: "oauth.scopes takes precedence over both authServerMetadataUrl and the scopes the server discovers at /.well-known. Leave it unset to let the MCP server determine the requested scope set." It then adds: "If the authorization server advertises offline_access in scopes_supported, Claude Code appends it to the pinned scopes so the access token can be refreshed without a new browser sign-in." Finally, line 801 states: "If the server later returns a 403 insufficient_scope for a tool call, Claude Code re-authenticates with the same pinned scopes."

Verdict: The current MCP page now explicitly documents the later 403 insufficient_scope failure mode and says Claude Code re-authenticates when it happens, which addresses the core missing behavior reported in the issue.

---

Claim 2: The docs omitted guidance for elevated scopes or renewed consent when more access is needed

Status: RESOLVED

At https://code.claude.com/docs/en/mcp, lines 781-781, the page says: "Set oauth.scopes to pin the scopes Claude Code requests during the authorization flow." At the same page, line 801 adds: "Widen oauth.scopes when a tool you need requires a scope outside the pin." The same page also still documents the user-facing OAuth flow at lines 652-670, including "Then follow the steps in your browser to login" (line 659) and "Use \"Clear authentication\" in the /mcp menu to revoke access" (line 667).

Verdict: The docs now explain how additional required access relates to oauth.scopes, and they still document the browser-based /mcp auth flow and Clear authentication recovery path. Together, that resolves the reported documentation gap around step-up re-authorization behavior.

---

Current State

| Claim | Status |
|-------|--------|
| Later 403 insufficient_scope and re-authentication behavior was undocumented | RESOLVED |
| Elevated-scope / renewed-consent guidance was undocumented | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

URL: https://code.claude.com/docs/en/mcp
Lines 652-670: Browser login flow and Clear authentication guidance in the /mcp flow
URL: https://code.claude.com/docs/en/mcp
Lines 781-801: oauth.scopes behavior, 403 insufficient_scope, and re-authentication guidance

---

Conclusion & Recommendation

Primary Concern: The issue reported that the MCP OAuth docs did not explain the later 403 insufficient_scope step-up re-authorization path for remote MCP servers.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current MCP documentation now explicitly describes the 403 insufficient_scope case, says Claude Code re-authenticates when it occurs, and explains how to widen oauth.scopes when additional access is needed. The reported documentation omission no longer appears in the current docs.

---