claude-code - 💡(How to fix) Fix [BUG] Claude Desktop skips RFC 8414 path-aware discovery and tries OIDC first for path-prefixed OAuth issuers

Describe the bug

When connecting to an MCP server with a path-prefixed OAuth issuer (e.g. https://mcp.example.com/myserver), Claude Desktop's OAuth discovery skips the RFC 8414 path-aware endpoint and instead tries OIDC Discovery first. This violates the MCP Authorization spec (2025-11-25) which requires RFC 8414 to be attempted first.

Steps to reproduce

1. Deploy a fastmcp-based MCP server with a path-prefixed public URL, e.g. https://mcp.example.com/myserver/mcp
2. Configure a Caddy reverse proxy with handle_path /myserver/* { reverse_proxy 127.0.0.1:8081 } (prefix is stripped before forwarding)
3. The server correctly implements:
   • GET /.well-known/oauth-authorization-server → 200 (RFC 8414, served by fastmcp)
   • OAuth issuer set to https://mcp.example.com/myserver
4. Add the server as a Claude Desktop Connector
5. Click "Connect"

Observed request sequence (from Caddy access log):

POST  /myserver/mcp                                          → 401  WWW-Authenticate: Bearer resource_metadata=...
GET   /.well-known/oauth-protected-resource/myserver/mcp    → 200  {"authorization_servers":["https://mcp.example.com/myserver"]}
GET   /myserver/.well-known/openid-configuration            → 404  (fastmcp does not implement this endpoint)
# Connection fails here — OAuth flow never completes

Missing from the sequence:

GET   /.well-known/oauth-authorization-server/myserver      → would return 200 (RFC 8414 path-aware)

Expected behavior

Per MCP Authorization spec 2025-11-25 §Authorization Server Metadata Discovery:

MCP clients MUST attempt multiple well-known endpoints…
For issuer URLs with path components (e.g. https://example.com/myserver), clients MUST try:

1. /.well-known/oauth-authorization-server/myserver (RFC 8414 §3.1 path-aware)
2. {issuer}/.well-known/openid-configuration (OIDC Discovery, fallback only)

Claude Desktop should request /.well-known/oauth-authorization-server/myserver first. Only if that returns a non-2xx response should it fall back to OIDC Discovery.

Actual behavior

Claude Desktop requests {issuer}/.well-known/openid-configuration without ever trying the RFC 8414 path-aware endpoint. Because fastmcp (and many other MCP server frameworks) do not implement /.well-known/openid-configuration, the discovery fails and the connection is aborted.

Workaround

Added a custom /.well-known/openid-configuration route in the MCP server application to proxy the response from /.well-known/oauth-authorization-server. This is a server-side shim for a client-side spec violation.

Environment

• Client: Claude Desktop (Connector feature), HTTP client identified as python-httpx/0.28.1
• MCP server: jquants-mcp (fastmcp + GitHubProvider)
• Reverse proxy: Caddy with path-prefix stripping (handle_path)
• MCP spec version advertised by client: 2025-11-25

Related

• fastmcp issue: https://github.com/PrefectHQ/fastmcp/issues/4166 (server-side analysis; fastmcp maintainers confirmed this is a client-side non-compliance)
• Similar discovery failure (different root cause): #31349