Repository navigation
Description
OAuth Metadata Discovery Should Respect Provided Authorization Server URL Before Applying RFC 8414 Path Construction
Description
The current OAuth metadata discovery implementation in src/client/auth.ts automatically applies RFC 8414 path-aware discovery patterns to authorization server URLs without first attempting to use the exact URL provided in the metadata. This causes failures when working with authorization servers like Keycloak that don't fully comply with RFC 8414 path construction but provide working endpoints.
Expected Behavior
When an authorization server URL is provided in the resource metadata (e.g., authorization_servers: ['http://localhost:9090/realms/mcp']), the SDK should:
- First attempt discovery at the exact provided URL +
/.well-known/oauth-authorization-server - Only if that fails, then attempt RFC 8414 path-aware discovery patterns
- Finally fall back to root discovery as currently implemented
Current Behavior
The SDK immediately applies RFC 8414 path-aware discovery, constructing URLs like:
http://localhost:9090/.well-known/oauth-authorization-server/realms/mcp
This fails with Keycloak and other authorization servers that don't implement RFC 8414 path-aware discovery but do provide working endpoints at the standard location.
Reproduction Steps
- Set up an authorization server that provides metadata with
authorization_servers: ['http://example.com/realms/test'] - Ensure the server has a working endpoint at
http://example.com/realms/test/.well-known/oauth-authorization-server - Run OAuth discovery with the TypeScript SDK
- Observe that it tries
http://example.com/.well-known/oauth-authorization-server/realms/test(404) instead of the working endpoint
Environment
- @modelcontextprotocol/sdk version: 1.15.0
- Authorization Server: Keycloak (known issue with RFC 8414 compliance: Compliant with RFC8414, return server metadata at /.well-known/oauth-authorization-server/realms/{realm} keycloak/keycloak#40923)
Relevant Code
The issue appears to be in discoverOAuthMetadata() function in src/client/auth.ts around lines 370-390, where path-aware discovery is attempted first without trying the direct URL.
Proposed Solution
Modify the discovery order in discoverOAuthMetadata() to:
- Try direct URL:
${authorizationServerUrl} - Try path-aware (current first attempt):
${origin}/.well-known/oauth-authorization-server${pathname} - Try root fallback (current second attempt):
${origin}/.well-known/oauth-authorization-server
This would maintain RFC 8414 compliance while being more practical for real-world authorization servers.
Additional Context
This issue affects interoperability with common authorization servers like Keycloak that provide functional OAuth metadata endpoints but don't implement the full RFC 8414 specification. The current implementation prioritizes strict RFC compliance over practical functionality.
Related Issues
This issue is related to but distinct from #616, which addresses falling back to .well-known/openid-configuration when .well-known/oauth-authorization-server fails entirely (e.g., with Google's authorization server).
The issues are complementary:
- Issue OAuth metadata discovery: fall back to openid-configuration #616: Handles cases where authorization servers don't provide
oauth-authorization-serverendpoints at all - This issue: Handles cases where authorization servers provide
oauth-authorization-serverendpoints but not at RFC 8414 path-aware locations
Both issues aim to improve compatibility with real-world authorization server implementations that don't fully conform to RFC 8414.
Note: I've searched existing issues and found the related issue #616 mentioned above. This follows the project's contributing guidelines for providing clear reproduction steps and context.
Activity
pcarleton commentedon Jul 14, 2025
Are there are other servers aside from Keycloak that you know of that have this problem? I wonder if fixing keycloak to support RFC 8414 would be a viable solution.
katesclau commentedon Jul 14, 2025
Hey @pcarleton , thanks for the response. Yes, it is a way of solving this - see keycloak/keycloak#40923 (comment)
But, regardless, when provided with a specific endpoint for authorization server, the client should check it contains the required information, specially if the URL provided as authorization server contains the
.well-known/oauth-authorization-serverin it. But I'm opened to discussion 😄MTG2000 commentedon Jul 16, 2025
We are also facing the same problem where we are using WorkOS and it returns the metadata on
https://something.authkit.app/.well-known/oauth-authorization-serverbut since our mcp is on a/mcppathname, the SDK is attempting to find the metadata onhttps://something.authkit.app/.well-known/oauth-authorization-server/mcpand it's failing with 404I think the problem is happening here:
typescript-sdk/src/client/auth.ts
Line 552 in 16ea277
The
metadataUrlinoptsis being ignored it seems in our case when the function is called with args:Is this the expected behaviour or is it a bug?
jpmcb commentedon Jul 21, 2025
Also facing the same problem with Okta based Oauth servers:
Okta OAuth resource servers are namespaced like:
https://{yourOktaDomain}/oauth2/{authorizationServerId}.This SDK creates the metadata as with the trailing metadata:
which is invalid and results in a 405.
Note: this directly affects testing servers with MCP inspector as well: modelcontextprotocol/inspector#634
pcarleton commentedon Jul 23, 2025
We're in the process of adding support for
openid-configurationas a valid metadata endpoint. OIDC config. As part of supporting that, we need to check appending.well-known/openid-configurationafter the path.Here's how it will look for an
authorization_servers: ["https://auth.example.com/oauth"]PRM entry:@jpmcb , @katesclau Will that work for both of these use cases?
Here's the PR for that:
#652
katesclau commentedon Jul 23, 2025
In this case, nothing changes for the
.well-known/oauth-authorization-serverdiscovery? the provided path will be added only after the.well-known/oauth-authorization-server, as currently is? If yes, I think it won't solve the existing issues with Okta and Keycloak - but I can test it to validate 😉I understand the current release implements RFC 8414 compliant, but the same RFC also suggest implementation of both patterns for compatibility.
ie.: for
authorization_servers: ["https://auth.example.com/oauth"]Thanks @pcarleton for the attention on this matter ❤️
pcarleton commentedon Jul 24, 2025
Hi it seems like this will work for Okta (just setup a trial account):
https://trial-4583365.okta.com/oauth2/default/.well-known/openid-configuration
and seems to work with keycloak as well:
curl http://localhost:8080/realms/master/.well-known/openid-configurationpcarleton commentedon Jul 24, 2025
Going to close this since it seems like the open ID compatibility work in this PR should fix it, but lmk if that's incorrect:
#652