fix: persist resource metadata URL across OAuth redirects

[hassan123789]

Motivation and Context

Fixes #1234

In browser OAuth flows, when the user is redirected to the authorization server and back, the resourceMetadataUrl discovered from the WWW-Authenticate header is lost. This causes token exchange to fail because the SDK cannot locate the correct token endpoint.

This is a critical issue for any browser-based MCP client implementing OAuth.

Solution

Added two optional methods to OAuthClientProvider:

• saveResourceMetadataUrl(url: URL): Saves the URL before redirect
• resourceMetadataUrl(): URL | undefined | Promise<URL | undefined>: Loads the saved URL after redirect

The SDK now:

1. Loads resourceMetadataUrl from provider if not passed in options (post-redirect)
2. Saves resourceMetadataUrl before calling redirectToAuthorization() (pre-redirect)

This follows the existing pattern used by saveCodeVerifier()/codeVerifier().

How Has This Been Tested?

• Added 6 unit tests covering:
  • Basic save/load functionality
  • Async (Promise) return values
  • Provider without implementation (backwards compatibility)
  • Options taking precedence over provider
  • Undefined return handling
• All 129 auth tests pass
• pnpm typecheck:all passes

Breaking Changes

None. Both methods are optional. Existing providers will continue to work without modification.

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

Additional context

Example browser implementation:

class BrowserOAuthProvider implements OAuthClientProvider {
  saveResourceMetadataUrl(url: URL): void {
    sessionStorage.setItem('oauth_resource_metadata_url', url.toString());
  }

  resourceMetadataUrl(): URL | undefined {
    const url = sessionStorage.getItem('oauth_resource_metadata_url');
    return url ? new URL(url) : undefined;
  }
}

[changeset-bot]

🦋 Changeset detected

Latest commit: a2d30d7

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	Patch

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

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

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

commit: a2d30d7

[pcarleton]

Thanks @hassan123789

I generally like this direction and think it will be useful. I wanted to propose a slight tweak to make it more extensible in the future. what do you think about this:

interface DiscoveryState {
  resourceMetadataUrl?: string;
  // Future additions as needed:
  // authorizationServerUrl?: string;
  // authorizationServerMetadata?: AuthorizationServerMetadata;
  // resource?: string;
}

interface OAuthClientProvider {
  // ... existing methods ...
  
  /**
   * Persists discovery state before redirecting to authorization.
   * Called alongside saveCodeVerifier() during authorization flow.
   */
  saveDiscoveryState?(state: DiscoveryState): void | Promise<void>;
  
  /**
   * Retrieves discovery state after redirect.
   * Returns undefined if not persisted or not implemented.
   */
  discoveryState?(): DiscoveryState | undefined | Promise<DiscoveryState | undefined>;
}

We can start with just resourceMetadataUrl, but if we decide to extend it in the future (to e.g. skip rediscovering auth endpoints, or if for some reason need to provide that data out of band), we can without needing to add new methods.