Add `{path}/.well-known/oauth-authorization-server` as a discovery URL fallback

[jerome3o-anthropic]

Problem

When discovering OAuth Authorization Server Metadata, the SDK currently tries the following URL patterns (via build_oauth_authorization_server_metadata_discovery_urls):

1. /.well-known/oauth-authorization-server{path} — RFC 8414 path-aware
2. /.well-known/openid-configuration{path} — RFC 8414 Section 5 OIDC path-aware
3. {path}/.well-known/openid-configuration — OIDC 1.0 discovery

However, it does not try {path}/.well-known/oauth-authorization-server.

Some OAuth providers (notably Azure Databricks) serve their OAuth Authorization Server Metadata at this path. For example:

https://<workspace>.azuredatabricks.net/oidc/.well-known/oauth-authorization-server

This returns a fully compliant metadata document with authorization_endpoint, token_endpoint, scopes_supported, code_challenge_methods_supported (PKCE), etc. — everything needed for a successful OAuth flow. Without discovering this metadata, clients fall back to incorrect default endpoints (e.g. /authorize instead of /oidc/v1/authorize) and wrong scopes.

Spec context

To be clear: {path}/.well-known/oauth-authorization-server is not the RFC 8414 URL construction. RFC 8414 Section 3 specifies that the well-known URI is inserted between the host and path components, producing /.well-known/oauth-authorization-server{path} — which the SDK already supports.

However, the SDK already supports the analogous non-RFC-8414 pattern for OIDC: {path}/.well-known/openid-configuration (pattern #3 above), which follows the OIDC 1.0 Discovery convention of appending the well-known suffix to the issuer URL. The missing pattern is simply the OAuth equivalent of this — same URL construction approach, different well-known suffix.

Proposal

Add {path}/.well-known/oauth-authorization-server as a fallback URL in the discovery logic, for consistency with the existing OIDC 1.0 support. The discovery order would become:

1. /.well-known/oauth-authorization-server{path} — RFC 8414
2. {path}/.well-known/oauth-authorization-server — OAuth equivalent of OIDC 1.0 pattern ← new
3. /.well-known/openid-configuration{path} — RFC 8414 Section 5
4. {path}/.well-known/openid-configuration — OIDC 1.0

This is a low-risk, one-line addition as a fallback URL that maintains consistency with the existing OIDC 1.0 support and unblocks real-world providers that use this convention.

[maxisbey]

Research: Discovery URL Patterns and Prior Discussions

Did some digging into the RFCs, MCP spec, conformance tests, and prior discussions across the ecosystem to provide context on this proposal.

RFC 8414 and OIDC Discovery: URL Construction Rules

RFC 8414 Section 3 defines a path-insertion construction — the well-known string is inserted between host and path. For issuer https://example.com/tenant1:

https://example.com/.well-known/oauth-authorization-server/tenant1

OIDC Discovery 1.0 uses a path-appending construction — the well-known suffix is concatenated after the issuer URL:

https://example.com/tenant1/.well-known/openid-configuration

The proposed {path}/.well-known/oauth-authorization-server is a hybrid: OIDC-style path-appending construction with the OAuth well-known suffix. This combination is not defined by RFC 8414 or OIDC Discovery. RFC 8414 Section 5 discusses OIDC compatibility fallback, but specifically refers to falling back to {path}/.well-known/openid-configuration (the OIDC suffix with OIDC construction), not applying the OIDC construction to the OAuth suffix.

MCP Spec (2025-11-25 and draft)

The spec explicitly enumerates the URLs clients MUST try for path-based issuers:

1. /.well-known/oauth-authorization-server{path} — RFC 8414
2. /.well-known/openid-configuration{path} — OIDC path insertion
3. {path}/.well-known/openid-configuration — OIDC 1.0 appending

{path}/.well-known/oauth-authorization-server is not in this list. The conformance tests test 4 discovery scenarios and none include this pattern.

Prior Discussions

This exact pattern has been discussed before across the ecosystem:

• typescript-sdk #1069 — @pcarleton explicitly addressed this pattern: "I don't want to support https://auth.example.com/oauth/.well-known/oauth-authorization-server as that's not compliant with RFC 8414, which says: 'Authorization servers supporting metadata MUST make a JSON document [...] available at a path formed by inserting a well-known URI string into the authorization server's issuer identifier between the host component and the path component, if any.'"

• typescript-sdk #744 — katesclau proposed this exact pattern (position 2 in a 5-URL discovery list) for Keycloak compatibility. The resolution was to add OIDC Discovery fallback ({path}/.well-known/openid-configuration) instead, since both Keycloak and Okta serve OIDC metadata at that location.

• python-sdk #1785 — sonmaximum reported the same Azure Databricks compatibility issue. @pcarleton responded that the discovery order intentionally follows the spec and pointed to the conformance tests. The reporter acknowledged Databricks is "OIDC compliant but seemingly not currently fully MCP spec compliant."

• typescript-sdk #545 — Broader discussion involving Okta, Keycloak, Azure Entra, WorkOS, and Asgardeo. Multiple community members advocated for more flexible discovery. The resolution was always OIDC fallback rather than non-standard OAuth path-appending.

• spec #1650 — Open issue arguing the MCP spec doesn't sufficiently specify its integration with RFC 8414, suggesting the spec should define explicit well-known URI suffixes and potentially an MCP-specific fallback chain.

The Consistency Argument

The issue's strongest point is the consistency argument: the SDK supports {path}/.well-known/openid-configuration (OIDC path-appending) but not the analogous {path}/.well-known/oauth-authorization-server. However, it's worth noting the OIDC path-appending pattern is defined by OIDC Discovery 1.0 (it's spec-compliant), while the OAuth path-appending pattern is not defined by any RFC.

Summary

Dimension	Finding
RFC basis	Not defined by RFC 8414 or any other RFC — hybrid of OIDC construction + OAuth suffix
MCP spec	Not in the current normative discovery URL list (2025-11-25 or draft)
Previously discussed	Yes — proposed in TS SDK #744, explicitly rejected; same provider issue in Python SDK #1785
Practical need	Real — Azure Databricks serves metadata at this path
Risk if added	Low — one extra HTTP request on failure paths as a last-resort fallback

Possible Paths Forward

1. Spec change first — propose adding this URL to the MCP spec's normative discovery order, then update the SDK to match
2. Provider-side fix — Azure Databricks could serve metadata at the RFC 8414 compliant location (/.well-known/oauth-authorization-server/oidc) or serve OIDC metadata at {path}/.well-known/openid-configuration (already supported)
3. Pragmatic SDK addition — add it as a last-resort fallback for real-world compatibility, acknowledging it's non-standard

@pcarleton — given the prior discussions (especially your comments on typescript-sdk #1069 and #744), would be good to get your take on whether the thinking here has evolved, particularly for cases like Azure Databricks where the OIDC fallback path doesn't resolve the issue.

_{AI Disclaimer}