Review OAuth discovery URL priority order for path-based vs root-based OIDC #1623
Description
Problem
The OAuth authorization server discovery URL priority in get_discovery_urls() (src/mcp/client/auth/utils.py:129-153) may not correctly prioritize path-based OIDC discovery over root-based discovery, which can cause issues with certain OAuth providers.
Context
This issue was flagged during review of PR #1586 (comment: #1586 (comment)) by @pcarleton:
jfyi: we need to change this, but do it carefully (see modelcontextprotocol/typescript-sdk#1103) likely better in a follow-up, but wanted to flag as you're rolling this out.
tl;dr having this root-based above path-based OIDC means we'll get the root-level metadata when there's a path-based one we should use.
The TypeScript SDK issue (#1103 in typescript-sdk) shows that changing discovery URL priority in v1.21.1 broke Jira MCP OAuth because the root-level well-known URLs returned 404 when path-based URLs should have been tried first.
Current Behavior
The current discovery URL order in get_discovery_urls() is:
- Path-aware OAuth:
/.well-known/oauth-authorization-server{path} - Root OAuth:
/.well-known/oauth-authorization-server - Path-aware OIDC:
/.well-known/openid-configuration{path} - OIDC fallback:
{server_url}/.well-known/openid-configuration
For a server like https://mcp.atlassian.com/v1/sse, this tries root-based OAuth discovery (#2) before path-based OIDC discovery (#3-4), which may fetch root-level metadata when path-based metadata should be preferred.
Desired Behavior
The discovery order should prioritize path-based OIDC appropriately, potentially before root-based OAuth discovery, to ensure we use the correct metadata for path-scoped OAuth providers.
Why This Needs Careful Handling
- This affects the core OAuth discovery flow
- Incorrect ordering can break OAuth with certain providers (as seen in TS SDK)
- The RFC 8414 specification needs to be carefully reviewed for correct priority
- Changes should be tested against multiple OAuth provider configurations
References
- PR refactor: extract OAuth helper functions and simplify provider state #1586: OAuth helper extraction refactor
- TypeScript SDK issue: 1.21.1 breaks Jira MCP OAuth typescript-sdk#1103
- RFC 8414 (OAuth 2.0 Authorization Server Metadata): https://www.rfc-editor.org/rfc/rfc8414.html
- RFC 8414 Section 5 (Path-aware OIDC): https://www.rfc-editor.org/rfc/rfc8414.html#section-5
- MCP Auth Spec: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
Related Code
src/mcp/client/auth/utils.py:129-153 - get_discovery_urls() function