fix(client): send the scope parameter on refresh-token requests

.changeset/refresh-token-scope-parameter.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Send the granted `scope` on refresh-token requests (RFC 6749 §6). `refreshAuthorization()` accepts a new optional `scope` and preserves the granted scope on its result when the response omits it (RFC 6749 §5.1); the built-in `auth()` flow sends exactly the granted scope recorded on the stored tokens (omitting the parameter when none is recorded). Fixes token refresh against authorization servers that require the parameter, e.g. Microsoft Entra ID rejecting scope-less refreshes with `AADSTS90009` when the client application is also the resource (#2718).

packages/client/src/client/auth.ts

@@ -1374,6 +1374,17 @@ async function authInternal(
                 metadata,
                 clientInformation,
                 refreshToken: tokens.refresh_token,
+                // RFC 6749 §6: the refresh-request scope must not exceed the originally
+                // granted scope, so send exactly the scope the AS recorded on the token
+                // response (RFC 6749 §5.1) and nothing else — a recomputed value (e.g.
+                // determineScope()'s output) could have widened since the grant and a
+                // strict AS would reject the refresh with invalid_scope. When no granted
+                // scope is recorded (absent or empty), omit the parameter, which the AS
+                // treats as the originally granted scope. Sending the granted scope keeps
+                // refresh working on servers that require the parameter — e.g. Microsoft
+                // Entra ID rejects a scope-less refresh with AADSTS90009 when the client
+                // application is also the resource (#2718).
+                scope: tokens.scope || undefined,
                 resource,
                 addClientAuthentication: provider.addClientAuthentication,
                 dpop: await provider.dpop?.(),
@@ -2334,6 +2345,7 @@ export async function refreshAuthorization(
         metadata,
         clientInformation,
         refreshToken,
+        scope,
         resource,
         addClientAuthentication,
         dpop,
@@ -2342,6 +2354,18 @@ export async function refreshAuthorization(
         metadata?: AuthorizationServerMetadata;
         clientInformation: OAuthClientInformationMixed;
         refreshToken: string;
+        /**
+         * Scope to request on the refresh, per RFC 6749 §6. MUST NOT include any scope
+         * not originally granted by the resource owner; when omitted (or empty), the
+         * authorization server treats the request as asking for the originally granted
+         * scope, so pass only the granted scope recorded on the token response
+         * (RFC 6749 §5.1) — never a recomputed or widened value.
+         *
+         * Some authorization servers require the parameter on refresh requests — e.g.
+         * Microsoft Entra ID (AAD) rejects a scope-less refresh with `AADSTS90009` when
+         * the client application is also the resource (#2718).
+         */
+        scope?: string;
         resource?: string | URL;
         addClientAuthentication?: OAuthClientProvider['addClientAuthentication'];
         /** SEP-1932 / RFC 9449: see {@linkcode executeTokenRequest}'s `dpop` option. */
@@ -2354,6 +2378,14 @@ export async function refreshAuthorization(
         refresh_token: refreshToken
     });
 
+    // Truthiness deliberate: an empty scope string means "the originally granted
+    // scope" exactly like an absent one, and a literal empty `scope=` parameter is
+    // syntactically invalid per RFC 6749 §3.3 (some ASes, e.g. GitHub, do record
+    // `"scope": ""` on token responses).
+    if (scope) {
+        tokenRequestParams.set('scope', scope);
+    }
+
     const tokens = await executeTokenRequest(authorizationServerUrl, {
         metadata,
         tokenRequestParams,
@@ -2364,8 +2396,11 @@ export async function refreshAuthorization(
         fetchFn
     });
 
-    // Preserve original refresh token if server didn't return a new one
-    return { refresh_token: refreshToken, ...tokens };
+    // Preserve the original refresh token if the server didn't return a new one, and
+    // the granted scope when the response omits it — RFC 6749 §5.1 lets the AS omit
+    // `scope` when it is identical to the requested scope, and dropping it here would
+    // strand the next refresh without the granted scope to send.
+    return { refresh_token: refreshToken, ...(scope ? { scope } : {}), ...tokens };
 }
 
 /**

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

@@ -2271,6 +2271,91 @@ describe('OAuth Authorization', () => {
             expect(tokens).toEqual({ refresh_token: refreshToken, ...validTokens });
         });
 
+        it('includes scope in the refresh request when provided (RFC 6749 §6, #2718)', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => validTokensWithNewRefreshToken
+            });
+
+            await refreshAuthorization('https://auth.example.com', {
+                clientInformation: validClientInfo,
+                refreshToken: 'refresh123',
+                scope: 'openid profile offline_access api://client123/access_as_user'
+            });
+
+            const body = mockFetch.mock.calls[0]![1].body as URLSearchParams;
+            expect(body.get('grant_type')).toBe('refresh_token');
+            expect(body.get('scope')).toBe('openid profile offline_access api://client123/access_as_user');
+        });
+
+        it('omits the scope parameter when none is provided', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => validTokensWithNewRefreshToken
+            });
+
+            await refreshAuthorization('https://auth.example.com', {
+                clientInformation: validClientInfo,
+                refreshToken: 'refresh123'
+            });
+
+            const body = mockFetch.mock.calls[0]![1].body as URLSearchParams;
+            expect(body.get('scope')).toBeNull();
+        });
+
+        it('omits the scope parameter when the granted scope is the empty string (RFC 6749 §3.3)', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => validTokensWithNewRefreshToken
+            });
+
+            // e.g. GitHub records `"scope": ""` on token responses with no scopes
+            await refreshAuthorization('https://auth.example.com', {
+                clientInformation: validClientInfo,
+                refreshToken: 'refresh123',
+                scope: ''
+            });
+
+            const body = mockFetch.mock.calls[0]![1].body as URLSearchParams;
+            expect(body.get('scope')).toBeNull();
+        });
+
+        it('preserves the granted scope when the refresh response omits it (RFC 6749 §5.1)', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                // No `scope` on the response: granted == requested
+                json: async () => validTokens
+            });
+
+            const tokens = await refreshAuthorization('https://auth.example.com', {
+                clientInformation: validClientInfo,
+                refreshToken: 'refresh123',
+                scope: 'api://client123/access_as_user'
+            });
+
+            expect(tokens.scope).toBe('api://client123/access_as_user');
+        });
+
+        it('prefers the scope from the refresh response over the requested one', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ ...validTokens, scope: 'narrowed' })
+            });
+
+            const tokens = await refreshAuthorization('https://auth.example.com', {
+                clientInformation: validClientInfo,
+                refreshToken: 'refresh123',
+                scope: 'api://client123/access_as_user'
+            });
+
+            expect(tokens.scope).toBe('narrowed');
+        });
+
         it('validates token response schema', async () => {
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -3047,6 +3132,91 @@ describe('OAuth Authorization', () => {
             expect(body.get('resource')).toBe('https://api.example.com/mcp-server');
             expect(body.get('grant_type')).toBe('refresh_token');
             expect(body.get('refresh_token')).toBe('refresh123');
+            // No granted scope was stored and none is resolvable — the parameter stays off the wire
+            expect(body.get('scope')).toBeNull();
+        });
+
+        it('sends the granted scope from the stored tokens on refresh (#2718)', async () => {
+            mockDiscoveryWithTokenEndpoint(() => ({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    access_token: 'new-access123',
+                    token_type: 'Bearer',
+                    expires_in: 3600
+                })
+            }));
+
+            (mockProvider.clientInformation as Mock).mockResolvedValue({
+                client_id: 'test-client',
+                client_secret: 'test-secret'
+            });
+            (mockProvider.tokens as Mock).mockResolvedValue({
+                access_token: 'old-access',
+                refresh_token: 'refresh123',
+                scope: 'api://test-client/access_as_user'
+            });
+            (mockProvider.saveTokens as Mock).mockResolvedValue(undefined);
+
+            const result = await auth(mockProvider, {
+                serverUrl: 'https://api.example.com/mcp-server'
+            });
+
+            expect(result).toBe('AUTHORIZED');
+
+            const tokenCall = mockFetch.mock.calls.find(call => call[0].toString().includes('/token'));
+            expect(tokenCall).toBeDefined();
+
+            const body = tokenCall![1].body as URLSearchParams;
+            expect(body.get('grant_type')).toBe('refresh_token');
+            expect(body.get('scope')).toBe('api://test-client/access_as_user');
+
+            // The mocked refresh response omits `scope` (granted == requested per
+            // RFC 6749 §5.1) — the granted scope must survive into the saved tokens
+            // so the NEXT refresh can send it too.
+            expect(mockProvider.saveTokens).toHaveBeenCalledWith(
+                expect.objectContaining({ scope: 'api://test-client/access_as_user' }),
+                expect.anything()
+            );
+        });
+
+        it('omits scope on refresh when the stored tokens carry no granted scope, even if a scope was requested (RFC 6749 §6)', async () => {
+            mockDiscoveryWithTokenEndpoint(() => ({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    access_token: 'new-access123',
+                    token_type: 'Bearer',
+                    expires_in: 3600
+                })
+            }));
+
+            (mockProvider.clientInformation as Mock).mockResolvedValue({
+                client_id: 'test-client',
+                client_secret: 'test-secret'
+            });
+            (mockProvider.tokens as Mock).mockResolvedValue({
+                access_token: 'old-access',
+                refresh_token: 'refresh123'
+            });
+            (mockProvider.saveTokens as Mock).mockResolvedValue(undefined);
+
+            const result = await auth(mockProvider, {
+                serverUrl: 'https://api.example.com/mcp-server',
+                scope: 'mcp:tools'
+            });
+
+            expect(result).toBe('AUTHORIZED');
+
+            const tokenCall = mockFetch.mock.calls.find(call => call[0].toString().includes('/token'));
+            expect(tokenCall).toBeDefined();
+
+            // The requested scope could exceed the original grant, so the refresh
+            // request must not carry a recomputed scope — omitted means "the
+            // originally granted scope" per RFC 6749 §6.
+            const body = tokenCall![1].body as URLSearchParams;
+            expect(body.get('grant_type')).toBe('refresh_token');
+            expect(body.get('scope')).toBeNull();
         });
 
         // The #2034 tests below differ only in how the token endpoint answers, so the