fix(client): preserve scopes across authorization retries

.changeset/sep-2350-scope-accumulation-followup.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Preserve previously requested OAuth scopes across Streamable HTTP, legacy SSE, automatic 401 handling, scope step-up, and `withOAuth`. Step-up unions explicit token, transport, and challenged scopes; when prior scope is unavailable, it reconstructs the initial protected-resource-metadata/provider fallback without over-requesting both.

docs/migration/upgrade-to-v2.md

@@ -848,7 +848,7 @@ hierarchy also exposes the same check as an explicit static guard
 TypeScript — use whichever style your codebase prefers; both read the same brand.
 Fine print (applies equally to `instanceof` and `isInstance`):
 
-- **Version skew** — matching needs *both* copies at a brand-aware release; against an
+- **Version skew** — matching needs _both_ copies at a brand-aware release; against an
   older copy, behavior degrades to plain prototype `instanceof` (false across bundles).
   During mixed-version rollouts, recognize errors without class identity: match
   `error.name` plus the class's discriminant field (`code`, `status`), or reconstruct
@@ -1230,9 +1230,14 @@ TLS; there is no opt-out. Storage confidentiality of `refresh_token` remains you
 
 `StreamableHTTPClientTransport` accepts `onInsufficientScope: 'reauthorize' | 'throw'`
 (default `'reauthorize'`). On `'reauthorize'` the transport re-authorizes with the
-**union** of the previously-requested and challenged scope (`computeScopeUnion`); when
-that union strictly exceeds the current token's granted scope (`isStrictScopeSuperset`),
-the SDK bypasses the refresh-token branch and forces a fresh authorization request. On
+**union** of the token grant, transport-tracked scope, and challenged scope
+(`computeScopeUnion`). If the token response omitted `scope` and the transport has no
+recorded request, it reconstructs the SDK's initial selection fallback — PRM
+`scopes_supported`, then provider `clientMetadata.scope` — without adding both.
+Automatic 401 handling and legacy SSE preserve that accumulated scope and the most
+recent resource-metadata URL. When the union strictly exceeds the
+current token's granted scope (`isStrictScopeSuperset`), the SDK bypasses the
+refresh-token branch and forces a fresh authorization request. On
 `'throw'` the transport raises `InsufficientScopeError` and does not re-authorize — set
 this for `client_credentials` / m2m clients where re-authorization can't widen scope, or
 to gate the consent prompt behind UX. Step-up retries are hard-capped per send

packages/client/src/client/auth.ts

@@ -55,6 +55,10 @@
     serverUrl: URL;
     /** Fetch function configured with the transport's `requestInit`, for making auth requests. */
     fetchFn: FetchLike;
+    /** Accumulated OAuth scope from previous challenges, if the transport has one. */
+    scope?: string;
+    /** Resource metadata URL from previous challenges, if the transport has one. */
+    resourceMetadataUrl?: URL;
 }
 
 /**
@@ -179,11 +183,15 @@
     ctx: UnauthorizedContext,
     extraAuthOptions?: Pick<AuthOptions, 'skipIssuerMetadataValidation'>
 ): Promise<void> {
-    const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(ctx.response);
+    const challenge = extractWWWAuthenticateParams(ctx.response);
+    const tokens = await provider.tokens();
+    const unionScope = computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope);
+    const forceReauthorization = isStrictScopeSuperset(unionScope, tokens?.scope);
     const result = await auth(provider, {
         serverUrl: ctx.serverUrl,
-        resourceMetadataUrl,
-        scope,
+        resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+        scope: unionScope,
+        ...(forceReauthorization ? { forceReauthorization } : {}),
         fetchFn: ctx.fetchFn,
         ...extraAuthOptions
     });

packages/client/src/client/middleware.ts

@@ -1,7 +1,7 @@
 import type { FetchLike } from '@modelcontextprotocol/core-internal';
 
 import type { OAuthClientProvider } from './auth';
-import { auth, extractWWWAuthenticateParams, UnauthorizedError } from './auth';
+import { auth, computeScopeUnion, extractWWWAuthenticateParams, isStrictScopeSuperset, UnauthorizedError } from './auth';
 
 /**
  * Middleware function that wraps and enhances fetch functionality.
@@ -39,11 +39,13 @@ export const withOAuth =
     (provider: OAuthClientProvider, baseUrl?: string | URL): Middleware =>
     next => {
         return async (input, init) => {
+            let lastTokenScope: string | undefined;
             const makeRequest = async (): Promise<Response> => {
                 const headers = new Headers(init?.headers);
 
                 // Add authorization header if tokens are available
                 const tokens = await provider.tokens();
+                lastTokenScope = tokens?.scope;
                 if (tokens) {
                     headers.set('Authorization', `Bearer ${tokens.access_token}`);
                 }
@@ -60,11 +62,14 @@ export const withOAuth =
 
                     // Use provided baseUrl or extract from request URL
                     const serverUrl = baseUrl || (typeof input === 'string' ? new URL(input).origin : input.origin);
+                    const unionScope = computeScopeUnion(lastTokenScope, scope);
+                    const forceReauthorization = lastTokenScope !== undefined && isStrictScopeSuperset(unionScope, lastTokenScope);
 
                     const result = await auth(provider, {
                         serverUrl,
                         resourceMetadataUrl,
-                        scope,
+                        scope: unionScope,
+                        ...(forceReauthorization ? { forceReauthorization } : {}),
                         fetchFn: next
                     });
 

packages/client/src/client/sse.ts

@@ -16,6 +16,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
     adaptOAuthProvider,
     auth,
+    computeScopeUnion,
     extractWWWAuthenticateParams,
     isOAuthClientProvider,
     resolveAuthorizationCallbackParams,
@@ -193,8 +194,8 @@ export class SSEClientTransport implements Transport {
                         this._last401Response = response;
                         if (response.headers.has('www-authenticate')) {
                             const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
-                            this._resourceMetadataUrl = resourceMetadataUrl;
-                            this._scope = scope;
+                            this._resourceMetadataUrl = resourceMetadataUrl ?? this._resourceMetadataUrl;
+                            this._scope = computeScopeUnion(this._scope, scope);
                         }
                     }
 
@@ -209,15 +210,23 @@ export class SSEClientTransport implements Transport {
                         const response = this._last401Response;
                         this._last401Response = undefined;
                         this._eventSource?.close();
-                        this._authProvider.onUnauthorized({ response, serverUrl: this._url, fetchFn: this._fetchWithInit }).then(
-                            // onUnauthorized succeeded → retry fresh. Its onerror handles its own onerror?.() + reject.
-                            () => this._startOrAuth().then(resolve, reject),
-                            // onUnauthorized failed → not yet reported.
-                            error => {
-                                this.onerror?.(error);
-                                reject(error);
-                            }
-                        );
+                        this._authProvider
+                            .onUnauthorized({
+                                response,
+                                serverUrl: this._url,
+                                fetchFn: this._fetchWithInit,
+                                resourceMetadataUrl: this._resourceMetadataUrl,
+                                scope: this._scope
+                            })
+                            .then(
+                                // onUnauthorized succeeded → retry fresh. Its onerror handles its own onerror?.() + reject.
+                                () => this._startOrAuth().then(resolve, reject),
+                                // onUnauthorized failed → not yet reported.
+                                error => {
+                                    this.onerror?.(error);
+                                    reject(error);
+                                }
+                            );
                         return;
                     }
                     const error = new UnauthorizedError();
@@ -357,15 +366,17 @@ export class SSEClientTransport implements Transport {
                 if (response.status === 401 && this._authProvider) {
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
-                        this._resourceMetadataUrl = resourceMetadataUrl;
-                        this._scope = scope;
+                        this._resourceMetadataUrl = resourceMetadataUrl ?? this._resourceMetadataUrl;
+                        this._scope = computeScopeUnion(this._scope, scope);
                     }
 
                     if (this._authProvider.onUnauthorized && !isAuthRetry) {
                         await this._authProvider.onUnauthorized({
                             response,
                             serverUrl: this._url,
-                            fetchFn: this._fetchWithInit
+                            fetchFn: this._fetchWithInit,
+                            resourceMetadataUrl: this._resourceMetadataUrl,
+                            scope: this._scope
                         });
                         await response.text?.().catch(() => {});
                         // Purposely _not_ awaited, so we don't call onerror twice

packages/client/src/client/streamableHttp.ts

@@ -213,11 +213,13 @@ export type StreamableHTTPClientTransportOptions = {
      * `WWW-Authenticate: Bearer error="insufficient_scope"`.
      *
      * - `'reauthorize'` (default): the transport runs the step-up authorization
-     *   flow — computes the union of the previously-requested scope and the
-     *   challenged scope, calls {@linkcode index.auth | auth()} (forcing a
-     *   fresh authorization request when the union strictly exceeds the current
-     *   token's granted scope, since refresh cannot widen scope per RFC 6749
-     *   §6), and retries the request once. Retries are bounded by
+     *   flow — computes the union of the current token's granted scope, the
+     *   previously requested scope, and the challenged scope. If no prior scope
+     *   was recorded, it reconstructs the initial PRM/provider fallback before
+     *   calling {@linkcode index.auth | auth()} (forcing a fresh authorization request
+     *   when the union strictly exceeds the current token's granted scope, since
+     *   refresh cannot widen scope per RFC 6749 §6), and retries the request once.
+     *   Retries are bounded by
      *   {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
      *   If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
      *   configured, step-up cannot run and the transport throws
@@ -398,10 +400,16 @@ export class StreamableHTTPClientTransport implements Transport {
             this._resourceMetadataUrl = challenge.resourceMetadataUrl;
         }
 
-        // Spec step-up: union of previously-requested scope and challenged scope,
-        // so previously-granted permissions are not lost on re-authorization.
+        // Spec step-up: preserve the explicit prior scope from the token and transport.
+        // Some authorization servers omit `scope` when it equals the request; if neither
+        // source records it, reconstruct the SDK's initial-selection fallback (PRM first,
+        // then provider default) rather than adding both and over-requesting permissions.
         const tokens = await this._oauthProvider.tokens();
-        const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+        const explicitPreviousScope = computeScopeUnion(tokens?.scope, this._scope);
+        const discoveryState = await this._oauthProvider.discoveryState?.();
+        const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+        const previousScope = explicitPreviousScope ?? (resourceScope || this._oauthProvider.clientMetadata.scope);
+        const unionScope = computeScopeUnion(previousScope, challenge.scope);
         this._scope = unionScope;
 
         // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -535,7 +543,7 @@ export class StreamableHTTPClientTransport implements Transport {
                 if (response.status === 401 && this._authProvider) {
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
-                        this._resourceMetadataUrl = resourceMetadataUrl;
+                        this._resourceMetadataUrl = resourceMetadataUrl ?? this._resourceMetadataUrl;
                         // Preserve any union accumulated by `_stepUpAuthorize` so a 401
                         // mid-chain does not narrow `_scope` back to the challenge value.
                         this._scope = computeScopeUnion(this._scope, scope);
@@ -545,7 +553,9 @@ export class StreamableHTTPClientTransport implements Transport {
                         await this._authProvider.onUnauthorized({
                             response,
                             serverUrl: this._url,
-                            fetchFn: this._fetchWithInit
+                            fetchFn: this._fetchWithInit,
+                            resourceMetadataUrl: this._resourceMetadataUrl,
+                            scope: this._scope
                         });
                         await response.text?.().catch(() => {});
                         // Purposely _not_ awaited, so we don't call onerror twice
@@ -984,7 +994,7 @@ export class StreamableHTTPClientTransport implements Transport {
                     // Store WWW-Authenticate params for interactive finishAuth() path
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
-                        this._resourceMetadataUrl = resourceMetadataUrl;
+                        this._resourceMetadataUrl = resourceMetadataUrl ?? this._resourceMetadataUrl;
                         // Preserve any union accumulated by `_stepUpAuthorize` so a 401
                         // mid-chain does not narrow `_scope` back to the challenge value.
                         this._scope = computeScopeUnion(this._scope, scope);
@@ -994,7 +1004,9 @@ export class StreamableHTTPClientTransport implements Transport {
                         await this._authProvider.onUnauthorized({
                             response,
                             serverUrl: this._url,
-                            fetchFn: this._fetchWithInit
+                            fetchFn: this._fetchWithInit,
+                            resourceMetadataUrl: this._resourceMetadataUrl,
+                            scope: this._scope
                         });
                         await response.text?.().catch(() => {});
                         // Purposely _not_ awaited, so we don't call onerror twice

packages/client/test/client/auth.test.ts

@@ -25,6 +25,7 @@ import {
     discoverOAuthServerInfo,
     exchangeAuthorization,
     extractWWWAuthenticateParams,
+    handleOAuthUnauthorized,
     InsecureTokenEndpointError,
     isHttpsUrl,
     isStrictScopeSuperset,
@@ -215,6 +216,87 @@ describe('OAuth Authorization', () => {
         });
     });
 
+    describe('handleOAuthUnauthorized', () => {
+        it('forces reauthorization with the full scope union instead of refreshing a narrower token', async () => {
+            const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+            const tokenEndpoint = 'https://auth.example.com/token';
+            const provider: OAuthClientProvider = {
+                get redirectUrl() {
+                    return 'http://localhost:3000/callback';
+                },
+                get clientMetadata() {
+                    return {
+                        redirect_uris: ['http://localhost:3000/callback'],
+                        client_name: 'Test Client'
+                    };
+                },
+                clientInformation: vi.fn().mockResolvedValue({ client_id: 'test-client' }),
+                tokens: vi.fn().mockResolvedValue({
+                    access_token: 'old-token',
+                    token_type: 'Bearer',
+                    refresh_token: 'refresh-token',
+                    scope: 'openid read'
+                }),
+                saveTokens: vi.fn(),
+                saveCodeVerifier: vi.fn(),
+                codeVerifier: vi.fn(),
+                redirectToAuthorization: vi.fn()
+            };
+            const response = new Response(null, {
+                status: 401,
+                headers: { 'WWW-Authenticate': 'Bearer scope="write"' }
+            });
+
+            mockFetch.mockImplementation(url => {
+                const urlString = url.toString();
+                if (urlString === resourceMetadataUrl.toString()) {
+                    return Promise.resolve(
+                        Response.json({
+                            resource: 'https://api.example.com/mcp',
+                            authorization_servers: ['https://auth.example.com']
+                        })
+                    );
+                }
+                if (urlString.includes('/.well-known/oauth-authorization-server')) {
+                    return Promise.resolve(
+                        Response.json({
+                            issuer: 'https://auth.example.com',
+                            authorization_endpoint: 'https://auth.example.com/authorize',
+                            token_endpoint: tokenEndpoint,
+                            response_types_supported: ['code'],
+                            code_challenge_methods_supported: ['S256']
+                        })
+                    );
+                }
+                if (urlString === tokenEndpoint) {
+                    return Promise.resolve(
+                        Response.json({
+                            access_token: 'refreshed-token',
+                            token_type: 'Bearer',
+                            scope: 'openid read'
+                        })
+                    );
+                }
+                return Promise.reject(new Error(`Unexpected fetch: ${urlString}`));
+            });
+
+            await expect(
+                handleOAuthUnauthorized(provider, {
+                    response,
+                    serverUrl: new URL('https://api.example.com/mcp'),
+                    fetchFn: mockFetch,
+                    resourceMetadataUrl,
+                    scope: 'read'
+                })
+            ).rejects.toBeInstanceOf(UnauthorizedError);
+
+            expect(mockFetch.mock.calls[0]?.[0].toString()).toBe(resourceMetadataUrl.toString());
+            expect(mockFetch.mock.calls.some(([url]) => url.toString() === tokenEndpoint)).toBe(false);
+            const authorizationUrl = (provider.redirectToAuthorization as Mock).mock.calls[0]?.[0] as URL;
+            expect(authorizationUrl.searchParams.get('scope')).toBe('openid read write');
+        });
+    });
+
     describe('isStrictScopeSuperset', () => {
         it.each([
             { union: undefined, current: undefined, expected: false },