fix(client): accumulate scopes (union) on step-up authorization challenges (SEP-2350)

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({

.changeset/sep-2350-scope-union-step-up.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Accumulate scopes (union) when re-authorizing after a `403 insufficient_scope` step-up challenge (SEP-2350). Previously the challenged scopes replaced the requested scope, so per-operation challenges dropped previously granted permissions. The client now requests the union of
+previously granted scopes (from stored tokens), previously requested scopes, protected resource metadata scopes, provider-configured default scopes, and the newly challenged scopes, using the existing exported `computeScopeUnion` helper.
+
+The 401 re-authorization path now preserves accumulated `scope` and `resourceMetadataUrl` context too: `UnauthorizedContext` exposes optional `scope` / `resourceMetadataUrl` fields for custom `AuthProvider.onUnauthorized` handlers, and `handleOAuthUnauthorized` folds that context into the next `auth()` call.
+
+The `withOAuth` fetch middleware likewise unions the stored token scope with the 401 challenge scope when re-authenticating.

docs/migration/upgrade-to-v2.md

@@ -1217,9 +1217,11 @@ 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 current token's granted scope, the previously-requested scope, protected
+resource metadata `scopes_supported`, the provider-configured default scope, and the
+newly 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
 `'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

@@ -53,6 +53,10 @@ export interface UnauthorizedContext {
  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;
 }
 
 /**
@@ -177,11 +181,12 @@ export async function handleOAuthUnauthorized(
  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 result = await auth(provider, {
  serverUrl: ctx.serverUrl,
- resourceMetadataUrl,
- scope,
+ resourceMetadataUrl: challenge.resourceMetadataUrl ?? ctx.resourceMetadataUrl,
+ scope: computeScopeUnion(tokens?.scope, ctx.scope, challenge.scope),
  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

@@ -14,6 +14,7 @@ import type { AuthProvider, OAuthClientProvider } from './auth';
 import {
  adaptOAuthProvider,
  auth,
+ computeScopeUnion,
  extractWWWAuthenticateParams,
  isOAuthClientProvider,
  resolveAuthorizationCallbackParams,
@@ -164,8 +165,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);
  }
  }
 
@@ -180,15 +181,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();
@@ -328,15 +337,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

@@ -212,11 +212,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, protected resource metadata scopes, provider
+ * default scope, and the challenged scope, then 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
  * {@linkcode StreamableHTTPClientTransportOptions.maxStepUpRetries | maxStepUpRetries}.
  * If no {@linkcode index.OAuthClientProvider | OAuthClientProvider} is
  * configured, step-up cannot run and the transport throws
@@ -397,10 +399,19 @@ 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: union the current token grant, the previously requested
+ // scope, PRM scopes_supported, provider default scope, and challenged
+ // scope so permissions are not lost on re-authorization.
  const tokens = await this._oauthProvider.tokens();
- const unionScope = computeScopeUnion(this._scope, tokens?.scope, challenge.scope);
+ const discoveryState = await this._oauthProvider.discoveryState?.();
+ const resourceScope = discoveryState?.resourceMetadata?.scopes_supported?.join(' ');
+ const unionScope = computeScopeUnion(
+ tokens?.scope,
+ this._scope,
+ resourceScope,
+ this._oauthProvider.clientMetadata.scope,
+ challenge.scope
+ );
  this._scope = unionScope;
 
  // Superset-gated refresh bypass: refresh cannot widen scope (RFC 6749 §6),
@@ -534,7 +545,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);
@@ -544,7 +555,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
@@ -983,7 +996,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);
@@ -993,7 +1006,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,71 @@ describe('OAuth Authorization', () => {
  });
  });
 
+ describe('handleOAuthUnauthorized', () => {
+ it('uses stored token scope, accumulated context scope, and resource metadata when reauthorizing', async () => {
+ const resourceMetadataUrl = new URL('https://resource.example.com/custom-prm');
+ 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', 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: 'https://auth.example.com/token',
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256']
+ })
+ );
+ }
+ 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());
+ 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 },

packages/client/test/client/middleware.test.ts

@@ -157,6 +157,42 @@ describe('withOAuth', () => {
  expect(retryHeaders.get('Authorization')).toBe('Bearer new-token');
  });
 
+ it('should union stored token scope with 401 challenge scope when re-authenticating', async () => {
+ mockProvider.tokens
+ .mockResolvedValueOnce({
+ access_token: 'old-token',
+ token_type: 'Bearer',
+ scope: 'read write'
+ })
+ .mockResolvedValueOnce({
+ access_token: 'new-token',
+ token_type: 'Bearer',
+ scope: 'read write admin'
+ });
+
+ const unauthorizedResponse = new Response('Unauthorized', {
+ status: 401,
+ headers: { 'www-authenticate': 'Bearer realm="oauth", scope="admin"' }
+ });
+ const successResponse = new Response('success', { status: 200 });
+
+ mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+ mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'admin' });
+ mockAuth.mockResolvedValue('AUTHORIZED');
+
+ const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+ await enhancedFetch('https://api.example.com/data');
+
+ expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+ serverUrl: 'https://api.example.com',
+ resourceMetadataUrl: undefined,
+ scope: 'read write admin',
+ forceReauthorization: true,
+ fetchFn: mockFetch
+ });
+ });
+
  it('should retry request after successful auth on 401 response (without baseUrl)', async () => {
  mockProvider.tokens
  .mockResolvedValueOnce({