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;
  }
}