feat: support oidc discovery in client sdk #652

xiaoyijun · 2025-06-18T02:58:51Z

This PR adds comprehensive OpenID Connect (OIDC) Discovery support to the client SDK, implementing the multi-protocol discovery strategy required by the latest MCP draft authorization specification.

🔄 MCP Draft Spec Compliant Discovery Strategy

Implements the exact discovery sequence mandated by the MCP Draft Spec:

For Authorization Server URLs with path components:
- OAuth 2.0 Authorization Server Metadata with path insertion
- OpenID Connect Discovery with path insertion
- OpenID Connect Discovery with path appending
For Authorization Server URLs without path components:
- OAuth 2.0 Authorization Server Metadata (/.well-known/oauth-authorization-server)
- OpenID Connect Discovery (/.well-known/openid-configuration)

✅ Specification Compliance

MUST support both OAuth 2.0 and OIDC discovery ✓
MUST verify code_challenge_methods_supported in OIDC metadata ✓
MUST implement proper path handling for discovery URLs ✓
MUST follow the exact discovery priority order ✓

🆕 New Types and Schemas

OpenIdProviderMetadataSchema — Full OIDC Discovery 1.0 provider metadata
OpenIdProviderDiscoveryMetadataSchema — Hybrid schema for real-world OIDC/OAuth2 mixed responses
AuthorizationServerMetadata — Union type supporting both OAuth 2.0 and OIDC metadata
Enhanced OAuthTokensSchema — With optional id_token field for OIDC compatibility

🔧 New Discovery Functions

discoverAuthorizationServerMetadata() — Main entry point implementing the draft spec’s discovery chain
Path-aware discovery with exact URL patterns per specification
Enhanced error handling with CORS retry logic and graceful 404 handling

⚡ Enhanced Authorization Flow

Support for OIDC offline_access scope with automatic prompt=consent
id_token handling in token responses
Full backward compatibility with legacy MCP servers

Motivation and Context

This change implements the latest MCP draft authorization specification requirements at https://modelcontextprotocol.io/specification/draft/basic/authorization, ensuring the SDK is compliant with the evolving MCP standard.

Significantly improves compatibility with modern identity providers (Keycloak, Auth0, Logto, etc.) that primarily use OIDC discovery
Maintains complete backward compatibility

How Has This Been Tested?

Unit tests have been added and updated, and all of them passed.

Breaking Changes

None. This change is fully backward-compatible:

Existing discoverOAuthMetadata() function preserved (marked deprecated)
Legacy MCP server behavior maintained as final fallback
All existing OAuth 2.0 functionality unchanged

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

xiaoyijun · 2025-06-18T03:02:49Z

Hi @pcarleton , thanks for the heads-up on the spec change! I've now implemented the corresponding OIDC discovery support in the SDK. Would you mind taking a look when you get a chance? Thanks~

dsp-ant · 2025-06-18T08:47:36Z

@ihrpr please hold merging this until we make a final decision if i want to actually have the #677 in the spec

dsp-ant

OICD and OAuth 2.0 AS metadata are no the same. They share a common base. We need to represent this in the type system appropriately so that clients can distinguish what to call.

This implement should have a common base interface that an OAuthMetadataSchema and an OICDMetadataSchema that inherit from it and discoverOAuthMetadata should return a Promise<OAuthMetadataSchema | OICDMetadataSchema | undefined>, that clients can discriminate on or downcast to the AuthserverBaseSchema.

dsp-ant · 2025-06-18T12:32:45Z

src/client/auth.ts

+const fetchWithCorsFallback = async (url: URL, protocolVersion: string) => {
+  try {
+    return await fetch(url, {
+      headers: {
+        "MCP-Protocol-Version": protocolVersion
+      }
+    })
+  } catch (error) {
+    if (error instanceof TypeError) {
+      // CORS errors come back as TypeError, try again without protocol version header
+      return await fetch(url);
+    }
+    throw error;
+  }
+}


This should be an async function fetchWithCorsFallback() and not const fetchWithCorsFallback =, to stay in line with everything else here and ensure that we define a proper return type.

dsp-ant · 2025-06-18T12:41:54Z

src/client/auth.ts

+    /**
+     * The `OAuthMetadataSchema` is compatible with both OIDC and OAuth2
+     * discovery responses. Because OIDC's metadata is a superset, `zod` will
+     * correctly parse the fields defined in our schema and simply ignore any
+     * additional OIDC-specific fields.
+     */
+    return OAuthMetadataSchema.parse(await response.json());


OICD is not a superset. They have a common base, but they do have both fields that they dont share, AS Metadata has introspection_endpoint, revocation_endpoint, introspection_endpoint_auth_methods_supported and OICD has userinfo_endpoint, subject_types_supported, id_token_signing_alg_values_supported for example.

pcarleton · 2025-06-18T18:53:48Z

tried adding more explicit typing here: main...feat-support-oidc-discovery-in-client-sdk

xiaoyijun · 2025-06-19T16:26:29Z

Hi @dsp-ant , thank you so much for the detailed review.
I will wait for the spec in modelcontextprotocol/modelcontextprotocol#677 (now it's modelcontextprotocol/modelcontextprotocol#797) to be finalized. Once it's merged, I'll update this PR to implement your suggestions.

xiaoyijun · 2025-06-19T16:33:22Z

Hi @pcarleton , thanks for your input and for highlighting the relevant code. Feel free to push directly to this branch if you'd like to collaborate on the changes. No worries if not, I'm happy to handle the refactoring myself once the spec is ready.
Thanks!

panva · 2025-06-24T17:22:11Z

@dsp-ant in response to the following comments:

OIDC and OAuth 2.0 AS metadata are not the same. They share a common base. We need to represent this in the type system appropriately so that clients can distinguish what to call.

They have a common base, but they do have both fields that they dont share, AS Metadata has introspection_endpoint, revocation_endpoint, introspection_endpoint_auth_methods_supported and OICD has userinfo_endpoint, subject_types_supported, id_token_signing_alg_values_supported for example.

The history of how Discovery 1.0 and RFC8414 came to be appears to give their nuance some credibility but at the end of the day they infact describe one and the same entity.

Both Discovery 1.0 and RFC8414 responses for the same issuer identifier describe the same Authorization Server, when resolved from a given issuer identifier they ought to return the same metadata.

In Discovery 1.0 > "Additional OpenID Provider Metadata parameters MAY also be used.".
In RFC8414 > "Additional authorization server metadata parameters MAY also be used. Some are defined by other specifications, such as OpenID Connect Discovery 1.0".
Both Discovery 1.0 and RFC8414 register metadata in the same IANA "OAuth Authorization Server Metadata" registry.

As a Client module developer my expectation is that I am able to resolve an issuer identifier to the two respective well-known URLs this issuer may host its AS metadata at and race to successful completion of either one.

Not having these endpoints return the same response when both are supported by the issuer has lead to client race conditions wrt. missing metadata in the past.

Therefore, the only typings related thing that may differ is the optionality of some of the properties, but not the properties themselves. They may (and in fact often do) all appear in both endpoints' responses.

xiaoyijun · 2025-07-20T00:44:23Z

Hi @dsp-ant @pcarleton @ihrpr , I hope you're all doing well.

The OIDC discovery spec has been merged into the draft authorization specification, and I've now fully implemented the OpenID Connect Discovery support as required by the latest MCP draft authorization specification.

When you have a moment, I'd appreciate your review. Thanks! 🙏

Adds validation during OIDC provider discovery to ensure S256 code challenge method is supported as required by MCP specification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Moves fallback logic back to individual functions instead of generating "fake" metadata during discovery. Discovery now returns undefined on 404 like the original code, maintaining the existing architectural pattern where functions handle their own URL fallbacks. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Implements root OAuth discovery fallback when path-aware discovery fails, restoring compatibility behavior from original code. Adds comprehensive RFC documentation for OAuth 2.0 Authorization Server Metadata (RFC 8414) and OpenID Connect Discovery 1.0 path handling rules. Discovery sequence for issuer with path components: 1. OAuth with path insertion (RFC 8414 Section 3.1) 2. OIDC with path insertion (RFC 8414 Section 5 compatibility) 3. OIDC with path appending (OIDC Discovery 1.0 Section 4.1) 4. OAuth root fallback for compatibility 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

pcarleton · 2025-07-23T11:11:01Z

👋 @xiaoyijun I have a few changes to add, but I need you to enable "maintainers can make changes to the branch":

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork

Changes are in this branch:
https://github.com/modelcontextprotocol/typescript-sdk/pull/new/pr-652

xiaoyijun · 2025-07-23T12:55:41Z

Hi @pcarleton , I can't see the "Allow edits and access to secrets by maintainers" checkbox, but I'm sure I've checked it when I create this PR.
Anyway, I will merge your branch into this one, thanks for your codes!

xiaoyijun · 2025-07-23T13:03:46Z

Hi @pcarleton , I have merged your commits into this branch. And maybe because I'm using my own fork, so you can't edit this PR.
Maybe you can try to use the github cli to checkout this PR in your local machine and change codes there.

Changes discovery sequence to be more logical and consistent: 1. Path-aware OAuth discovery 2. Root OAuth discovery (if path exists) 3. OIDC discovery methods This ensures OAuth methods are exhausted before trying OIDC, providing more predictable fallback behavior. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Removes tests that are now covered by the parameterized discovery sequence tests, eliminating duplication while maintaining full coverage of all discovery scenarios. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

LucaButBoring · 2025-07-23T21:08:13Z

src/client/auth.ts

+    }
+
+    if (!response.ok) {
+      if (response.status === 404) {


Can we continue on any 4XX (#804)? The spec doesn't specify that fallbacks should only occur on 404s. I put out an equivalent fix on the Python side just now here: modelcontextprotocol/python-sdk#1193.

I was planning to open a PR for this independently, but that would directly conflict with this PR, I think.

yea good call, added it in my branch

pcarleton · 2025-07-24T10:31:25Z

@xiaoyijun I've added a few more changes in main...pr-652 can you pull those in here?

(re: whether the maintainers setting is selected, the only way I know of to check is this view. If Edit File is grayed out, it means the "Allow edits from maintainers" option has not been selected:

)

xiaoyijun · 2025-07-24T13:02:16Z

@pcarleton Thanks for the heads up! I’ll make sure to select the “Allow edits from maintainers” option next time. (It seems I wasn’t able to enable this option because of how my branch settings.)

I’ve just merged the latest changes from main (pr-652) as well. If there’s anything else, feel free to tag me!

pcarleton

LGTM

(outdated branch)

xiaoyijun mentioned this pull request Jun 18, 2025

feat: enhance auth server discovery with OAuth2 and OIDC metadata support modelcontextprotocol/modelcontextprotocol#677

Merged

9 tasks

xiaoyijun force-pushed the feat-support-oidc-discovery-in-client-sdk branch from 0b3f1bc to cf64a97 Compare June 18, 2025 03:48

ihrpr linked an issue Jun 18, 2025 that may be closed by this pull request

enhance auth server discovery with OAuth2 and OIDC metadata support #653

Closed

dsp-ant previously requested changes Jun 18, 2025

View reviewed changes

joshcanhelp mentioned this pull request Jun 19, 2025

feat: allow OIDC configuration for OAuth server #585

Open

9 tasks

ihrpr added this to the auth milestone Jun 25, 2025

joshcanhelp mentioned this pull request Jun 25, 2025

Feature: Add an OIDC configuration flag geelen/mcp-remote#102

Closed

xiaoyijun mentioned this pull request Jul 17, 2025

feat: enhance auth server discovery with OAuth2 and OpenID metadata support modelcontextprotocol/modelcontextprotocol#797

Merged

9 tasks

xiaoyijun added 2 commits July 18, 2025 22:04

feat: support oidc discovery in client sdk

be90ac5

chore: rebased

3bb5f3e

xiaoyijun force-pushed the feat-support-oidc-discovery-in-client-sdk branch from cf64a97 to a3fe322 Compare July 19, 2025 16:35

xiaoyijun requested a review from a team as a code owner July 19, 2025 16:35

xiaoyijun requested review from a team, pcarleton and ihrpr July 19, 2025 16:35

xiaoyijun added 2 commits July 20, 2025 00:56

feat: apply draft spec

5375f46

chore: revert tests

997b850

xiaoyijun force-pushed the feat-support-oidc-discovery-in-client-sdk branch from a3fe322 to 2de25f0 Compare July 19, 2025 17:01

test: add unit tests

69619b9

xiaoyijun force-pushed the feat-support-oidc-discovery-in-client-sdk branch 2 times, most recently from e0b4ffe to bcbaa86 Compare July 19, 2025 17:30

chore: revert format changes

c148ef1

xiaoyijun force-pushed the feat-support-oidc-discovery-in-client-sdk branch from bcbaa86 to c148ef1 Compare July 19, 2025 17:31

xiaoyijun requested a review from dsp-ant July 20, 2025 00:38

pcarleton self-assigned this Jul 23, 2025

pcarleton and others added 3 commits July 23, 2025 10:51

feat: add S256 PKCE validation for OIDC discovery

ecb76f1

Adds validation during OIDC provider discovery to ensure S256 code challenge method is supported as required by MCP specification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

pcarleton mentioned this pull request Jul 23, 2025

OAuth Metadata Discovery should respect provided Authorization Server URL before applying RFC 8414 path construction #744

Closed

pcarleton and others added 3 commits July 23, 2025 16:10

clean up unused param

c8ccd03

LucaButBoring reviewed Jul 23, 2025

View reviewed changes

pcarleton added 5 commits July 24, 2025 10:57

simplify fetching logic

90f6eca

test discovery urls list

49b51f5

cleanup

0b2c0b1

simplify path construction

ab060e1

permit all 4xx status codes to continue probing

a6fd8f5

xiaoyijun requested a review from a team as a code owner July 24, 2025 12:59

pcarleton approved these changes Jul 24, 2025

View reviewed changes

pcarleton merged commit bb7cccc into modelcontextprotocol:main Jul 24, 2025
2 checks passed

This was referenced Jul 24, 2025

feat: 3 phase discovery for oauth metadata discovery #797

Closed

issue/744 - Uses authorization server url provided by .well-known/oauth-protected-resource metadata #748

Closed

feat: support oidc discovery in client sdk #652

feat: support oidc discovery in client sdk #652

Conversation

xiaoyijun commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

xiaoyijun commented Jun 18, 2025

Uh oh!

dsp-ant commented Jun 18, 2025

Uh oh!

dsp-ant left a comment

Choose a reason for hiding this comment

Uh oh!

dsp-ant Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

dsp-ant Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

pcarleton commented Jun 18, 2025

Uh oh!

xiaoyijun commented Jun 19, 2025

Uh oh!

xiaoyijun commented Jun 19, 2025

Uh oh!

panva commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xiaoyijun commented Jul 20, 2025

Uh oh!

pcarleton commented Jul 23, 2025

Uh oh!

xiaoyijun commented Jul 23, 2025

Uh oh!

xiaoyijun commented Jul 23, 2025

Uh oh!

LucaButBoring Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

pcarleton Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

pcarleton commented Jul 24, 2025

Uh oh!

xiaoyijun commented Jul 24, 2025

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

xiaoyijun commented Jun 18, 2025 •

edited

Loading

panva commented Jun 24, 2025 •

edited

Loading