[DOCS] MCP OAuth docs omit RFC 9728 authorization-server discovery

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Authenticate with remote MCP servers, especially Use pre-configured OAuth credentials and Override OAuth metadata discovery

Current Documentation

The docs currently say:

Some MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like "Incompatible auth server: does not support dynamic client registration," the server requires pre-configured credentials. Claude Code also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server. If your MCP server returns errors on the standard OAuth metadata endpoint (/.well-known/oauth-authorization-server) but exposes a working OIDC endpoint, you can tell Claude Code to fetch OAuth metadata directly from a URL you specify, bypassing the standard discovery chain.

No documentation currently explains how Claude Code discovers the authorization server from the MCP server URL.

What's Wrong or Missing?

Changelog v2.1.85 says:

MCP OAuth now follows RFC 9728 Protected Resource Metadata discovery to find the authorization server

The MCP page documents OAuth setup, CIMD support, and the authServerMetadataUrl override, but it does not explain the automatic discovery behavior that now happens before that override is needed.

A. Automatic authorization-server discovery is undocumented

The page never says that Claude Code starts from the MCP server URL and uses RFC 9728 Protected Resource Metadata discovery to locate the authorization server.

B. The current “standard discovery chain” wording is too vague for troubleshooting

Users cannot tell whether Claude Code expects OAuth metadata on the MCP server origin itself or whether it can discover a separate authorization server from protected-resource metadata.

C. The relationship between automatic discovery and authServerMetadataUrl is unclear

The override is documented, but not when it is necessary versus when RFC 9728 discovery should succeed automatically.

Suggested Improvement

Add a short explanation to the MCP OAuth section that documents the discovery flow and how the override fits into it. For example:

For remote MCP servers that use OAuth, Claude Code starts from the MCP server URL and follows RFC 9728 Protected Resource Metadata discovery to locate the authorization server. It then fetches OAuth server metadata from that authorization server. If your provider's discovery metadata is missing or broken, set oauth.authServerMetadataUrl to point directly to the OAuth/OIDC metadata document.

Also note that this matters when the authorization server is hosted on a different origin than the MCP server.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Remote MCP OAuth setup and discovery override guidance currently documents CIMD and authServerMetadataUrl but not RFC 9728 authorization-server discovery |

Total scope: 1 page affected

Source: Changelog v2.1.85

Changelog entry:

MCP OAuth now follows RFC 9728 Protected Resource Metadata discovery to find the authorization server