[DOCS] MCP OAuth docs do not clarify that unset `oauth.scopes` should avoid requesting the full `scopes_supported` catalog

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Restrict OAuth scopes" subsection for remote MCP servers.

Current Documentation

The MCP page currently says:

"Set oauth.scopes to pin the scopes Claude Code requests during the authorization flow. This is the supported way to restrict an MCP server to a security-team-approved subset when the upstream authorization server advertises more scopes than you want to grant."

"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."

"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."

The page does not explicitly warn that leaving oauth.scopes unset should not cause Claude Code to request the authorization server's entire scopes_supported catalog.

What's Wrong or Missing?

Claude Code v2.1.196 fixed MCP OAuth requesting the authorization server's full scopes_supported catalog when no scope is specified, which caused invalid_scope failures on GitLab self-hosted and other enterprise identity providers. The docs say "leave it unset to let the MCP server determine the requested scope set", but they do not explain the concrete failure mode that can happen when a client over-requests every advertised scope.

Suggested Improvement

Add a note under "Restrict OAuth scopes":

If oauth.scopes is unset, Claude Code should not request every value advertised in the authorization server's scopes_supported metadata. It lets the MCP server or authorization challenge determine the needed scope set. Pin oauth.scopes only when your organization wants to constrain or explicitly request a known scope set.

Also add a troubleshooting sentence for enterprise IdPs:

If a self-hosted GitLab or enterprise IdP returns invalid_scope, check whether the server requires an explicit smaller oauth.scopes value rather than the full advertised catalog.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Remote MCP OAuth scope configuration |

Total scope: 1 page affected.

Claude Code v2.1.196 fixed invalid_scope failures caused by requesting a server's full scopes_supported catalog when no explicit scope was configured.