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

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:

| 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