feat: expose discoverOAuthServerInfo() and add provider caching for auth server URL

[felixweinberger]

Summary

Extracts the RFC 9728 + authorization server metadata discovery logic from authInternal() into a new public discoverOAuthServerInfo() function, and adds unified discovery state caching to OAuthClientProvider.

Motivation and Context

MCP clients need the authorization server URL for operations outside the auth() orchestrator — specifically token refresh and token revocation. Currently, the SDK discovers this URL via RFC 9728 inside authInternal() but never exposes it, forcing consumers to reimplement the discovery logic.

Additionally, browser-based OAuth flows lose discovery state (including the resourceMetadataUrl from WWW-Authenticate headers) during redirects, causing token exchange failures (#1234, #1350).

Key Changes

discoverOAuthServerInfo(serverUrl, opts?) (new export)
Combines RFC 9728 protected resource metadata discovery with authorization server metadata discovery into a single call. Returns OAuthServerInfo { authorizationServerUrl, authorizationServerMetadata?, resourceMetadata? }.

OAuthDiscoveryState (new type)
Unified type for persisting all discovery results: auth server URL, resource metadata URL, resource metadata, and auth server metadata.

OAuthClientProvider changes (non-breaking)

• saveDiscoveryState?(state) — called by auth() after discovery so providers can persist all discovery results
• discoveryState?() — returns cached state; when present, auth() restores discovery results instead of re-discovering
• invalidateCredentials scope union extended with 'discovery' for clearing cached discovery state

authInternal() refactored to use discoverOAuthServerInfo() and the unified caching. Cached path restores full discovery state including resource metadata, preserving the resource parameter in token requests.

This subsumes the use case from #1350 (persisting resourceMetadataUrl across browser redirects) — the URL is now part of OAuthDiscoveryState.

How Has This Been Tested?

• 8 new test cases covering discoverOAuthServerInfo() and discovery state caching
• Tests verify resource parameter is preserved on cached path
• All 253 client tests pass
• Full typecheck and lint pass

Breaking Changes

None. All additions are optional interface methods, new exports, and a new union member for an optional method parameter.

Types of changes

• New feature (non-breaking change which adds functionality)

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

Additional context

Co-authored with @hassan123789 whose #1350 identified the resourceMetadataUrl persistence problem that this unified approach addresses.

[changeset-bot]

🦋 Changeset detected

Latest commit: cb7b55c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/client	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1527

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1527

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1527

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1527

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1527

commit: cb7b55c

[pcarleton]

generally like the idea, but i'd prefer if we made it flexible to store more discovery state:
#1350

this would make it easier to squirrel away the PRM URL, OASM URL, scope, resource parameter. Also makes it easier to provide those things out of band, e.g. if you've discovered them previously and want to just load them, or if there's something wrong with discovery (e.g. a 503 is de-railing the discovery process).

[ochafik]

I'll defer to @pcarleton for approval but added a few questions :-)

[felixweinberger]

generally like the idea, but i'd prefer if we made it flexible to store more discovery state: #1350

this would make it easier to squirrel away the PRM URL, OASM URL, scope, resource parameter. Also makes it easier to provide those things out of band, e.g. if you've discovered them previously and want to just load them, or if there's something wrong with discovery (e.g. a 503 is de-railing the discovery process).

Sure! We can cajole #1350 in potentially? @ochafik thoughts?

[pcarleton]

lgtm, couple non-blocking

[pcarleton]

Can this type and OAuthDiscoveryState be the same?

[felixweinberger]

I think they're a little bit different right, they just happen to look similar right now - but in future the OAuthDiscoveryState (what gets saved) could diverge meaningfully from OAuthServerInfo?

To avoid duplication though makes sense for OAuthDiscoveryState to extend OAuthServerInfo though, so changed that here - wdyt?

[pcarleton]

cool that makes sense to me