[DOCS] MCP OAuth docs omit step-up re-authorization for `403 insufficient_scope`

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Authenticate with remote MCP servers, especially the /mcp browser login flow and token refresh guidance

Current Documentation

The docs currently say:

In Claude code, use the command: /mcp Then follow the steps in your browser to login. Tips: Authentication tokens are stored securely and refreshed automatically Use "Clear authentication" in the /mcp menu to revoke access

No documentation currently explains what happens when a remote MCP server asks for additional OAuth scopes after the initial authorization is already in place.

What's Wrong or Missing?

Changelog v2.1.85 says:

Fixed MCP step-up authorization failing when a refresh token exists — servers requesting elevated scopes via 403 insufficient_scope now correctly trigger the re-authorization flow

The MCP page documents initial browser login and automatic token refresh, but it does not explain the distinct step-up authorization case.

A. Elevated-scope re-authorization is undocumented

Users are not told that a remote MCP server can respond with 403 insufficient_scope to request additional scopes, and that Claude Code should send them back through the browser authorization flow to grant those scopes.

B. The relationship between refresh and re-authorization is unclear

The page says tokens are "refreshed automatically," but does not clarify that refresh is not enough when the server needs broader scopes. Users cannot tell why an already authenticated server may need another browser authorization step.

Suggested Improvement

Add a short note in the remote MCP OAuth section explaining step-up authorization. For example:

If a remote MCP server responds with 403 insufficient_scope, Claude Code treats that as a step-up authorization request and starts the browser re-authorization flow so you can approve the additional scopes. This can happen even when an existing refresh token is present, because refresh reuses the scopes already granted rather than requesting broader access.

Optionally mention that /mcp is the place to inspect the server and retry or clear authentication if needed.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary Claude Code page for remote MCP OAuth setup; documents initial login and automatic token refresh but not step-up re-authorization for 403 insufficient_scope |

Total scope: 1 page affected

Source: Changelog v2.1.85

Changelog entry:

Fixed MCP step-up authorization failing when a refresh token exists — servers requesting elevated scopes via 403 insufficient_scope now correctly trigger the re-authorization flow