Using the built in auth router, the issuer URL is not fully utilized for the authorization endpoint

[localden]

Describe the bug

For example, I might want to be able to use the Microsoft Entra ID authorization experience:

app.use(mcpAuthRouter({
  provider: provider,
  issuerUrl: new URL('https://login.microsoftonline.com/TENANT_ID/v2.0'),
  serviceDocumentationUrl: new URL('https://den.dev'),
  authorizationOptions: {},
  tokenOptions: {}
}));

However, on the client side, when implementing OAuthClientProvider, this gets "cleaned" and only the domain makes it through, leading to an auth URL being something like this:

https://login.microsoftonline.com/authorize?response_type=code&client_id=SOMETHING_HERE&code_challenge=gEuH28apn6iVPB0hy5zCzpBzB13OXdpImHwp6y_W_JE&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A11780

Which will, of course, 404, since it doesn't exist.

This stems from the generated OAuth metadata (in /.well-known/oauth-authorization-server):

{
  "issuer": "https://login.microsoftonline.com/TENANT_ID/v2.0",
  "service_documentation": "https://den.dev/",
  "authorization_endpoint": "https://login.microsoftonline.com/authorize",
  "response_types_supported": [
    "code"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint": "https://login.microsoftonline.com/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "revocation_endpoint": "https://login.microsoftonline.com/revoke",
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_post"
  ],
  "registration_endpoint": "https://login.microsoftonline.com/register"
}

Now, one might argue that mcpAuthRouter was not designed for other issuers, like Microsoft Entra ID, which would be fine. But I am curious if this is by-design behavior for integrating with third-party identity providers or not.

[localden]

I think this comes on the heels of how URL concatenation works - if you remove the prefix / from the endpoint constants (instead of /authorize you have authorize) and also ensure that the issuer URL ends with / (to prevent the last bit from being treated like a file), it works:

authorization_endpoint: new URL(authorization_endpoint, issuer.href.endsWith('/') ? issuer : `${issuer}/`).href

[allenzhou101]

Personally, I wonder if the right abstraction here is to instead allow an override of the metadata oauth endpoints instead of automatically constructing them in the same format since it's possible the external provider doesn't even conform to the the same specific OAuth syntax for each endpoint (eg. authorize vs token).

In general, seems there are two main options for integrating OAuth providers like Descope, Auth0, Microsoft.

• Include external provider OAuth endpoints directly in MCP Server metadata
• Hide external provider OAuth endpoints behind local MCP Server OAuth endpoints in MCP Server metadata but handle logic to call under the hood

Trade-offs

• Option 1: Lower latency and simpler implementation but less control. If the provider lacks certain features (e.g., a state parameter), MCP can’t compensate.

• Option 2: More control but higher latency and complexity.

Implementation

The current MCP Typescript SDK codebase includes the OAuthServerProvider and mcpAuthRouter.

To support both use cases, we could introduce a ProxyOAuthServerProvider that implements the OAuthServerProvider. It would accept external OAuth endpoints (authorize, token, metadata, etc.) along with functions to get client info (eg. approved redirect uris) and verify access tokens. It would also implement the other required methods for the fallback urls to work but the user of the class wouldn't need to worry about this.

For Option 1, we’ll need to add a parameter to say we should override the existing metadata URL construction for the OAuth endpoints. This would then include theProxyOAuthServerProvider endpoints directly in the MCP Server metadata document. This would better manage the multitude of ways in which OAuth endpoints can be constructed, since they don't necessarily have to append the same paths to the issuer.

For Option 2, we can simply include this provider as the param in the mcpAuthRouter. We’ll also need to add an attribute to tell the router to skip local pkce verification as the upstream server would handle this. This will hide the external auth provider endpoints behind the MCP fallback routes so the client would call those through the metadata instead.

This would adjust the design of the mcpAuthRouter to support first and third-party issuers. Also, this could better cover edge cases where maybe you'd only want to use external endpoints for particular urls in the metadata while keeping others local.

[localden]

Personally, I wonder if the right abstraction here is to instead allow an override of the metadata oauth endpoints instead of automatically constructing them in the same format since it's possible the external provider doesn't even conform to the the same specific OAuth syntax for each endpoint (eg. authorize vs token).

I agree, I think that would be a reasonable approach here. I can't speak for other providers, but in the context of Microsoft's Entra ID and Entra External ID you might end up in situations where the URLs can't quite be constructed uniformly. For example, take a look at Microsoft Entra External ID:

https://wggdemo.ciamlogin.com/818fbfd7-0338-45d3-8cc8-8d521cc578b2/v2.0/.well-known/openid-configuration

Notice that the /token endpoint is:

https://wggdemo.ciamlogin.com/818fbfd7-0338-45d3-8cc8-8d521cc578b2/oauth2/v2.0/token

And the JWKs endpoint is:

https://wggdemo.ciamlogin.com/818fbfd7-0338-45d3-8cc8-8d521cc578b2/discovery/v2.0/keys

Granted, the /token and JWKs endpoints serve different purposes, but it illustrates the problem that in some cases it will be impossible to reliably and deterministically set up the endpoints in a consistent manner.

In terms of trade-offs, I am always leaning towards simplicity. As a developer, I know that I would rather not implement the OAuth spec or OAuth server requirements from scratch if I can use something like Microsoft Entra ID or Okta/Auth0 out-of-the-box. You will end up with some gaps, for sure (e.g., MCP server client registration), but maybe that is a fair trade-off because - if I am operating under the constraints of the public client space (i.e., my local box talking to some MCP server), I might already have a client registration with the identity provider.

cc: @jerome3o-anthropic

[localden]

Adding some additional context, @allenzhou101 @jerome3o-anthropic.

The lens that I am looking through here is that ideally, when building a server, we wouldn't need to use two sets of credentials (e.g., MCP server generating its own tokens) and instead rely on an identity provider (e.g., Entra ID, Okta/Auth0) for both legs of the process. At a high level, this is the flow I have in mind, assuming that the client acts as a public client application (additional work might be needed here):

sequenceDiagram
    participant B as Browser (User Agent)
    participant C as Client
    participant S as MCP Server
    participant M as Microsoft Entra ID
    participant R as Protected API

    C->>S: Send request to `/authorize` (listening for auth code)
    S->>C: Return the Entra ID authorization URL
    C->>B: Navigate to URL and authenticate with API scopes
    B->>C: Return auth code
    C->>M: Redeem auth code
    M->>C: Return access token (AT)
    C->>C: Store/cache AT
    C->>S: Send authenticated request with Microsoft Entra ID AT
    S->>S: Validate token
    S->>M: Redeem token for on-behalf-of (OBO) token with resource scopes
    M->>S: Return OBO token
    S->>R: Request user information
    R->>S: Return user information
    S->>C: Return user information

Loading

Note

This assumes that the client knows how to redeem an auth code for a AT (e.g., by using an OAuth library)

Using the current version of the TypeScript SDK as well as reading through the specification, it seems like the desire is for the server to still be minting its own tokens in addition to the third-party service tokens. Is that the case? This statement makes me think it is:

MCP server generates its own access token bound to the third-party session

This seems somewhat suboptimal if I want to exclusively use a third-party IdP.

[allenzhou101]

@localden Agree with your points!

With regards to this note:

MCP server generates its own access token bound to the third-party session

I think the token binding is more so referring to if the MCP Server is wanting to integrate functionality of different services like Github or Jira. So the MCP Server would still only have one token to issue to the MCP Client (either issuing itself or using an external provider like Microsoft, Descope, or Auth0). It's just that that token would then be used to get the tokens used to integrate with the Github or Jira API endpoints on behalf of the user.

So the MCP Server would only generate one credential for the MCP Client (whether directly or via external provider) but it may handle more upstream provider tokens if the server uses them.

[localden]

@allenzhou101 - so that's the part that needs some clarity in terms of documenting (and implementing, probably) the canonical integration flow, to make sure that developers don't go down the path of implementing their own JWT infrastructure.

Sounds like the format would be this (I am using JWT loosely here - it can be any token):

graph LR
    Client[MCP Client] <-->|JWT_0| Server[MCP Server]
    Server -->|JWT_0_OBO| Azure[Azure]
    Server -->|JWT_2| Stripe[Stripe]
    Server -->|JWT_3| GitHub[GitHub]

    style Client fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ecf0f1
    style Server fill:#3498db,stroke:#2980b9,stroke-width:2px,color:#ecf0f1
    style Azure fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ecf0f1
    style Stripe fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ecf0f1
    style GitHub fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ecf0f1

Loading

Here, JWT_0 is the "core" IdP used, JWT_0_OBO is a derivative of the initial JWT (in the context of on-behalf-of flows), and JWT_1 and JWT_2 are completely different JWTs.

On the surface, that makes sense. Let's take Descope as an example IdP here. I, as the server developer, would use Descope to implement the initial public client flow between client and server, so the client will then have a Descope JWT that it can use to auth against the server. The MCP server in this context doesn't actually need to mint its own token or maintain a mapping between some variant of its own token and the Descope token. That would make this part of the spec irrelevant then:

Maintain secure mapping between third-party tokens and issued MCP tokens

Because you'd have one token, no?

That also raises an interesting side-case here, and that is if the server needs to talk to many services that require the user to authorize them (e.g., Descope won't handle all of them), how does that auth flow back to the customer (or is that even a desired scenario)?

If I need to log in with Dropbox (let's assume that Descope doesn't federate with it and the server doesn't hold a Dropbox secret until auth). How is that channeled back to the user, since the IdP here would be different than the Descope one?

[allenzhou101]

In this case, the Descope JWT could map to the other IdPs like Dropbox. Either this could involve setting the Dropbox JWT as a claim in the Descope one or storing the Dropbox one in the cloud and fetching via Descope JWT.

If the Dropbox one were to expire before Descope, you could throw a 401 or SSE Unauthorized to have the client reauth and the authorize flow would go through Dropbox consent. This could also be handled custom outside of Descope (in terms of the mapping).

[allenzhou101]

So my thought is that maybe the spec would need to define an SSE event that would tell the client to reauth and the same auth flow could be used to get the Dropbox token as long as the flow includes starting oauth with Dropbox.

[localden]

@allenzhou101 - do you have a reference implementation with Descope that you can share? I am working on one for Entra ID and it seems a bit complex for a seemingly simple 3P IdP integration. Will share my repo/write-up tomorrow, but curious if you have already tackled a simple demo with your IdP.

[allenzhou101]

@localden We don't quite have a reference implementation yet, more of a work in progress. However, we do have a working demo set up here that relies on a fork of the MCP TS SDK linked in this PR. It's an MCP Server that leverages Descope to expose Descope API functionality like searching audit logs for a project.

We've tested with the MCP Inspector and it works fine with Dynamic Client Registration, Authorization Code flow, etc.

If you wanted to chat about it synchronously I'd be happy to find a time too--always happy to learn from one another.

[allenzhou101]

Basically, it adds a ProxyOAuthServerProvider implementation of the OAuthServerProvider interface that's part of the MCP TS SDK. Then, in the Descope MCP Server itself has an implementation of OAuthServerProvider here.

[localden]

@allenzhou101 your approach is similar to my, more "hacky" solution. There's some challenges, here, however, as we are trying to keep the feet on two sides of the fence - public and confidential client in one server.

Would love to chat synchronously to see where we can join forces (happy to contribute to your PR in the context of Entra ID integration). Send me a note to den@microsoft.com and I'll set up some time.

[d-henn]

Hey all, do you happen to know if there is progress on this work? Also ran into this while trying to use Entra as the provider (along with some other things, like no support for Dynamic Client Registration); wondering if a clean solution has been identified or if there is another solution I should be going after.

Regards!