client: preserve OAuth discovery metadata across browser redirects

[windro-xdd]

Summary

• persist interactive OAuth metadata (resource_metadata URL and scope) in browser sessionStorage for both Streamable HTTP and SSE client transports
• restore that state on transport construction so finishAuth() works after full-page redirects
• clear persisted state after successful authorization to avoid stale auth context
• add regression tests for transport recreation + post-redirect finishAuth() on both transports

Why

finishAuth() can fail in browser redirect flows when the original transport instance is lost and the WWW-Authenticate metadata extracted before redirect is no longer in memory. Persisting and restoring this metadata keeps token exchange on the same discovered authorization path.

Validation

• pnpm --filter @modelcontextprotocol/client typecheck
• pnpm --filter @modelcontextprotocol/client lint
• pnpm --filter @modelcontextprotocol/client test -- test/client/streamableHttp.test.ts test/client/sse.test.ts

Closes #1234

[changeset-bot]

🦋 Changeset detected

Latest commit: 317fec5

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

This PR includes changesets to release 7 packages

Name	Type
@modelcontextprotocol/server	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/express	Patch
@modelcontextprotocol/fastify	Patch
@modelcontextprotocol/hono	Patch
@modelcontextprotocol/node	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

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1816

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1816

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1816

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1816

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1816

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1816

commit: 317fec5

[pcarleton]

Hi, you should be able to do this with loadDiscoveryState / saveDiscoveryState, could be in an example implementation of OAuthProvider

[km-anthropic]

@claude review

[felixweinberger]

@claude review

[claude]

🔴 The new OAuthProvider class in packages/client/src/providers/oauthProvider.ts has two critical bugs that make it non-functional. Line 19 imports from "../client/index.js", but no index.ts barrel exists in packages/client/src/client/ — this is a compilation error that prevents the file from building. Additionally, createTransportWithRestoredState() accepts resourceMetadataUrl and scope options but silently ignores them: it creates a bare StreamableHTTPClientTransport with empty options {} and only emits a console.debug message, leaving the restored state completely unapplied. Since _resourceMetadataUrl and _scope are private fields on StreamableHTTPClientTransport with no public setter, there is also no architectural path to inject the state. OAUTH_REDIRECT_EXAMPLE.md documents createTransportWithRestoredState() as the recommended redirect-recovery pattern, so users following the docs will silently lose all recovered state.

Extended reasoning...

Bug 1: Broken import path (compilation error)

oauthProvider.ts line 19 imports:
import { StreamableHTTPClientTransport } from "../client/index.js";

The file lives at packages/client/src/providers/oauthProvider.ts, so ../client/ resolves to packages/client/src/client/. That directory contains auth.ts, sse.ts, streamableHttp.ts, stdio.ts, etc. — but no index.ts barrel file. TypeScript's module resolution cannot find ../client/index.js and will emit a TS2307 error at compile time.

The correct import is either "../client/streamableHttp.js" (direct file) or "../index.js" (the package-level barrel at packages/client/src/index.ts, which does export StreamableHTTPClientTransport). The tsconfig.json for the client package uses "include": ["./"] which recursively includes all TypeScript files — so oauthProvider.ts will be compiled. The test at packages/client/test/providers/oauthProvider.test.ts directly imports from oauthProvider.js, so both pnpm typecheck and pnpm test would fail.

Step-by-step proof:

1. TypeScript resolves "../client/index.js" to packages/client/src/client/index.ts (or .tsx, .d.ts).
2. No such file exists in the directory.
3. Build fails with TS2307 before any runtime code executes.
4. Fix: change to "../client/streamableHttp.js".

Bug 2: createTransportWithRestoredState() is a no-op

createTransportWithRestoredState() is the entire point of the OAuthProvider class — it is called after an OAuth redirect to recreate a transport with previously-discovered metadata. The implementation:

const transport = new StreamableHTTPClientTransport(new URL(url), {});
// If we have restored state, we could apply it to the transport
// or use it to configure subsequent discovery requests
if (options?.resourceMetadataUrl) {
console.debug("[OAuthProvider] Restored discovery state...", options.resourceMetadataUrl);
}
return transport;

The comment "we could apply it to the transport" is an explicit marker of a deferred/incomplete placeholder. The options parameter is accepted but never used: the transport is constructed with empty options {}, and the only action taken when resourceMetadataUrl is present is a console.debug call.

Why this cannot be fixed externally: StreamableHTTPClientTransport stores _resourceMetadataUrl and _scope as private fields (lines 173-174 of streamableHttp.ts). There is no public setter for either field, so createTransportWithRestoredState() cannot inject the restored state from outside the class.

Contrast with SSEClientTransport: This PR correctly implements sessionStorage persistence for SSEClientTransport (_loadInteractiveAuthState called in constructor, _saveInteractiveAuthState called on 401). StreamableHTTPClientTransport receives NO equivalent sessionStorage code, making createTransportWithRestoredState() the only intended mechanism for state restoration after a redirect — and that mechanism is broken.

Step-by-step proof of the broken flow:

1. User follows OAUTH_REDIRECT_EXAMPLE.md: calls oauthProvider.saveDiscoveryState({ resourceMetadataUrl: 'https://...', scope: 'read' }) before redirect.
2. After redirect, calls oauthProvider.loadDiscoveryState() which returns { resourceMetadataUrl: 'https://...', scope: 'read', timestamp: ... }.
3. Calls oauthProvider.createTransportWithRestoredState('https://api.example.com', { resourceMetadataUrl: 'https://...', scope: 'read' }).
4. Method executes: new StreamableHTTPClientTransport(new URL(url), {}) — options are ignored entirely.
5. Returns transport with _resourceMetadataUrl = undefined and _scope = undefined.
6. Subsequent finishAuth() call re-runs full discovery from scratch, losing the restored metadata URL.
7. Token exchange may fail or use the wrong discovery path — the redirect recovery is silently broken.

[claude]

🔴 StreamableHTTPClientTransport is missing the sessionStorage persistence that this PR claims to implement for it. The PR description states "persist interactive OAuth metadata (resource_metadata URL and scope) in browser sessionStorage for both Streamable HTTP and SSE client transports", but only SSEClientTransport received the implementation. In a real browser redirect flow, the new StreamableHTTPClientTransport instance will start with undefined _resourceMetadataUrl and _scope and must redo full OAuth discovery on every post-redirect finishAuth() call — unlike SSEClientTransport, which restores from sessionStorage. The test named "persists interactive auth metadata across transport recreation before finishAuth" passes only because all discovery responses are mocked; the sessionStorage mock set up in beforeEach is never exercised by StreamableHTTPClientTransport.

Extended reasoning...

What the bug is

The PR title and description explicitly state it persists OAuth discovery state "for both Streamable HTTP and SSE client transports", but StreamableHTTPClientTransport has zero sessionStorage implementation. A grep for "sessionStorage", "_saveInteractiveAuthState", "_loadInteractiveAuthState", or "_clearInteractiveAuthState" in packages/client/src/client/streamableHttp.ts returns no results in this PR. The feature is only half-implemented.

The specific code path that triggers it

SSEClientTransport (sse.ts) gained all three lifecycle methods:

• Constructor: calls _loadInteractiveAuthState() to restore persisted metadata
• On 401 response: calls _saveInteractiveAuthState() after extracting WWW-Authenticate params
• After finishAuth(): calls _clearInteractiveAuthState() to prevent stale state

streamableHttp.ts received none of these. The file was changed in this PR for reconnection, Accept header merging, and error-response handling — but the OAuth state persistence that is the core stated goal is absent.

Why existing code does not prevent it

The test "persists interactive auth metadata across transport recreation before finishAuth" in streamableHttp.test.ts is misleadingly named. The test sets up a sessionStorage mock in beforeEach (matching the SSE test), but StreamableHTTPClientTransport never reads from or writes to sessionStorage. The test works because the mock fetch provides four successive responses: 401 (first transport), resource metadata, auth server metadata, and token exchange (second transport). The second transport finishAuth() succeeds by doing full fresh discovery from the mocked data — not by restoring persisted state. This gives a false impression that the feature was implemented and tested.

Impact

In production browser redirect flows without mocked network calls:

1. Server temporarily unreachable during callback: finishAuth() will fail even though the original 401 response captured the resource metadata URL. SSEClientTransport would succeed because it has the URL in sessionStorage.
2. Extra network calls: every post-redirect finishAuth() triggers redundant metadata discovery, adding latency and failure surface.
3. Inconsistency between transports: the stated PR goal of consistent behavior across both transports is not achieved.

How to fix it

StreamableHTTPClientTransport needs the same three private methods that SSEClientTransport has, with an appropriate storage key prefix (e.g. "mcp:oauth:interactive:streamablehttp:"). The constructor should call _loadInteractiveAuthState(), the 401-handling path should call _saveInteractiveAuthState() after extracting WWW-Authenticate params, and finishAuth() should call _clearInteractiveAuthState() after successful authorization.

Step-by-step proof

1. Browser makes MCP request via StreamableHTTPClientTransport; server returns 401 with a WWW-Authenticate header containing the resource_metadata URL and scope.
2. Transport stores _resourceMetadataUrl and _scope in memory. Without _saveInteractiveAuthState(), nothing is written to sessionStorage.
3. App redirects the user to the OAuth provider. The original transport instance is destroyed (full page navigation).
4. OAuth provider redirects back to the callback page. App creates a new StreamableHTTPClientTransport.
5. Without _loadInteractiveAuthState(), _resourceMetadataUrl is undefined and _scope is undefined.
6. finishAuth('auth-code') calls auth() with resourceMetadataUrl: undefined, forcing a full re-discovery network call.
7. If the discovery endpoint is temporarily unreachable during the callback, finishAuth() throws — even though the metadata URL was successfully captured before the redirect. An SSEClientTransport in the same scenario would succeed using the sessionStorage-cached URL.