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:

1. Path-aware OAuth: /.well-known/oauth-authorization-server{path}
2. Root OAuth: /.well-known/oauth-authorization-server
3. Path-aware OIDC: /.well-known/openid-configuration{path}
4. 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