fix(client): accumulate OAuth scopes on 401/403 instead of overwriting

Replace direct this._scope = scope assignments with mergeScopes() that unions
existing and incoming scope strings via Set deduplication. Prevents infinite
re-auth loops when servers use per-operation progressive authorization
(RFC 6750 §3.1).

Fixes #1582

Author: rechedev9

.changeset/fix-scope-overwrite-infinite-reauth.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Fix: accumulate OAuth scopes on 401/403 instead of overwriting
+
+When an HTTP transport receives a 401 or 403 with a `WWW-Authenticate` header
+containing new scopes, the scopes are now merged with any previously-acquired scopes
+rather than replacing them. The previous behaviour could cause an infinite re-auth loop
+where the client repeatedly lost its original scopes each time it attempted to upscope.

packages/client/src/client/sse.ts

@@ -6,6 +6,21 @@ import { EventSource } from 'eventsource';
 import type { AuthProvider, OAuthClientProvider } from './auth.js';
 import { adaptOAuthProvider, auth, extractWWWAuthenticateParams, isOAuthClientProvider, UnauthorizedError } from './auth.js';
 
+/**
+ * Merges two space-separated OAuth scope strings into a deduplicated union.
+ * Returns undefined when the resulting set is empty.
+ * Preserves insertion order of first occurrence for determinism.
+ */
+function mergeScopes(existing: string | undefined, incoming: string | undefined): string | undefined {
+    const existingTokens = existing?.split(/\s+/).filter(Boolean) ?? [];
+    const incomingTokens = incoming?.split(/\s+/).filter(Boolean) ?? [];
+    const merged = new Set<string>([...existingTokens, ...incomingTokens]);
+    if (merged.size === 0) {
+        return undefined;
+    }
+    return [...merged].join(' ');
+}
+
 export class SseError extends Error {
     constructor(
         public readonly code: number | undefined,
@@ -136,7 +151,7 @@ export class SSEClientTransport implements Transport {
                         if (response.headers.has('www-authenticate')) {
                             const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
                             this._resourceMetadataUrl = resourceMetadataUrl;
-                            this._scope = scope;
+                            this._scope = mergeScopes(this._scope, scope);
                         }
                     }
 
@@ -271,7 +286,7 @@ export class SSEClientTransport implements Transport {
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
                         this._resourceMetadataUrl = resourceMetadataUrl;
-                        this._scope = scope;
+                        this._scope = mergeScopes(this._scope, scope);
                     }
 
                     if (this._authProvider.onUnauthorized && !isAuthRetry) {

packages/client/src/client/streamableHttp.ts

@@ -16,6 +16,21 @@ import { EventSourceParserStream } from 'eventsource-parser/stream';
 import type { AuthProvider, OAuthClientProvider } from './auth.js';
 import { adaptOAuthProvider, auth, extractWWWAuthenticateParams, isOAuthClientProvider, UnauthorizedError } from './auth.js';
 
+/**
+ * Merges two space-separated OAuth scope strings into a deduplicated union.
+ * Returns undefined when the resulting set is empty.
+ * Preserves insertion order of first occurrence for determinism.
+ */
+function mergeScopes(existing: string | undefined, incoming: string | undefined): string | undefined {
+    const existingTokens = existing?.split(/\s+/).filter(Boolean) ?? [];
+    const incomingTokens = incoming?.split(/\s+/).filter(Boolean) ?? [];
+    const merged = new Set<string>([...existingTokens, ...incomingTokens]);
+    if (merged.size === 0) {
+        return undefined;
+    }
+    return [...merged].join(' ');
+}
+
 // Default reconnection options for StreamableHTTP connections
 const DEFAULT_STREAMABLE_HTTP_RECONNECTION_OPTIONS: StreamableHTTPReconnectionOptions = {
     initialReconnectionDelay: 1000,
@@ -222,7 +237,7 @@ export class StreamableHTTPClientTransport implements Transport {
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
                         this._resourceMetadataUrl = resourceMetadataUrl;
-                        this._scope = scope;
+                        this._scope = mergeScopes(this._scope, scope);
                     }
 
                     if (this._authProvider.onUnauthorized && !isAuthRetry) {
@@ -515,7 +530,7 @@ export class StreamableHTTPClientTransport implements Transport {
                     if (response.headers.has('www-authenticate')) {
                         const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
                         this._resourceMetadataUrl = resourceMetadataUrl;
-                        this._scope = scope;
+                        this._scope = mergeScopes(this._scope, scope);
                     }
 
                     if (this._authProvider.onUnauthorized && !isAuthRetry) {
@@ -554,7 +569,7 @@ export class StreamableHTTPClientTransport implements Transport {
                         }
 
                         if (scope) {
-                            this._scope = scope;
+                            this._scope = mergeScopes(this._scope, scope);
                         }
 
                         if (resourceMetadataUrl) {

packages/client/test/client/sse.test.ts

@@ -1171,6 +1171,87 @@ describe('SSEClientTransport', () => {
             await expect(() => transport.start()).rejects.toMatchObject(expectedError);
             expect(mockAuthProvider.invalidateCredentials).toHaveBeenCalledWith('tokens');
         });
+
+        it('accumulates scopes from sequential 401 responses in send()', async () => {
+            // Create server that accepts SSE connection but returns 401 on POST
+            // with different scopes on successive requests
+            resourceServer.close();
+
+            let postCallCount = 0;
+            resourceServer = createServer((req, res) => {
+                lastServerRequest = req;
+
+                if (req.method === 'GET') {
+                    if (req.url !== '/') {
+                        res.writeHead(404).end();
+                        return;
+                    }
+
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache, no-transform',
+                        Connection: 'keep-alive'
+                    });
+                    res.write('event: endpoint\n');
+                    res.write(`data: ${resourceBaseUrl.href}\n\n`);
+                    return;
+                }
+
+                if (req.method === 'POST') {
+                    postCallCount++;
+                    if (postCallCount === 1) {
+                        // First POST: 401 with scope="read:op1"
+                        res.writeHead(401, {
+                            'WWW-Authenticate': 'Bearer scope="read:op1"'
+                        });
+                        res.end();
+                    } else if (postCallCount === 2) {
+                        // Second POST: 401 with scope="read:op2"
+                        res.writeHead(401, {
+                            'WWW-Authenticate': 'Bearer scope="read:op2"'
+                        });
+                        res.end();
+                    } else {
+                        res.writeHead(200);
+                        res.end();
+                    }
+                }
+            });
+
+            resourceBaseUrl = await listenOnRandomPort(resourceServer);
+
+            // Use a minimal AuthProvider (not OAuthClientProvider) so onUnauthorized
+            // is not set and 401 throws UnauthorizedError, letting us inspect _scope.
+            const minimalAuthProvider: AuthProvider = {
+                token: vi.fn().mockResolvedValue('test-token')
+            };
+
+            transport = new SSEClientTransport(resourceBaseUrl, {
+                authProvider: minimalAuthProvider
+            });
+
+            await transport.start();
+
+            const message: JSONRPCMessage = {
+                jsonrpc: '2.0',
+                id: '1',
+                method: 'test',
+                params: {}
+            };
+
+            // First send: 401 with scope="read:op1" — throws UnauthorizedError
+            await expect(transport.send(message)).rejects.toThrow(UnauthorizedError);
+            expect((transport as unknown as { _scope: string | undefined })['_scope']).toBe('read:op1');
+
+            // Second send: 401 with scope="read:op2" — scope should accumulate
+            await expect(transport.send(message)).rejects.toThrow(UnauthorizedError);
+
+            // Verify _scope has accumulated both tokens
+            const finalScope = (transport as unknown as { _scope: string | undefined })['_scope'];
+            expect(finalScope).toBeDefined();
+            const finalScopeTokens = String(finalScope).split(' ').toSorted();
+            expect(finalScopeTokens).toEqual(['read:op1', 'read:op2']);
+        });
     });
 
     describe('custom fetch in auth code paths', () => {