feat(client): add getAuthorizationCode() to OAuthClientProvider for headless OAuth flows

- Add optional `getAuthorizationCode()` method to `OAuthClientProvider` interface
- Update `withOAuth` middleware to automatically complete the authorization code
  exchange when the provider implements `getAuthorizationCode()` after a REDIRECT
- Handle 403 responses the same as 401 in `withOAuth` (upscoping)
- Update conformance `ConformanceOAuthProvider` to implement `getAuthorizationCode()`
- Update conformance `withOAuthRetry` to use the new method name and remove TODO

Closes #1370

Author: rechedev9

.changeset/feat-oauth-retry-getauthorizationcode-1370.md

@@ -0,0 +1,13 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add `getAuthorizationCode()` to `OAuthClientProvider` for headless OAuth flows
+
+The `withOAuth` middleware now supports completing the authorization code exchange
+automatically when the provider implements the new optional `getAuthorizationCode()`
+method. This enables headless environments (CI, test harnesses, CLI tools) where the
+OAuth redirect can be intercepted programmatically.
+
+Additionally, `withOAuth` now handles `403` responses the same as `401`, since a 403
+can indicate the server requires a broader scope (upscoping).

packages/client/src/client/auth.ts

@@ -146,6 +146,28 @@ export interface OAuthClientProvider {
      */
     invalidateCredentials?(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void | Promise<void>;
 
+    /**
+     * If implemented, returns the authorization code obtained after the user completes
+     * the OAuth authorization flow. This is called by {@linkcode withOAuth} immediately
+     * after {@linkcode OAuthClientProvider.redirectToAuthorization | redirectToAuthorization()}
+     * resolves, allowing the middleware to automatically complete the token exchange without
+     * requiring manual intervention.
+     *
+     * **Ordering contract:** The authorization code *must* be available by the time this
+     * method is called. Because `redirectToAuthorization()` is awaited first, the typical
+     * pattern is to capture and store the code inside `redirectToAuthorization()` so that
+     * it is ready to return here. Throwing from this method will propagate as an
+     * {@linkcode UnauthorizedError}.
+     *
+     * Implement this when your provider handles the authorization callback inline —
+     * for example, by starting a local HTTP server that catches the redirect, or by
+     * fetching the authorization URL directly in a headless environment.
+     *
+     * If not implemented, {@linkcode withOAuth} will throw an {@linkcode UnauthorizedError}
+     * when a redirect is required, leaving it to the caller to manage the auth code flow.
+     */
+    getAuthorizationCode?(): string | Promise<string>;
+
     /**
      * Prepares grant-specific parameters for a token request.
      *

packages/client/src/client/middleware.ts

@@ -53,23 +53,38 @@ export const withOAuth =
 
             let response = await makeRequest();
 
-            // Handle 401 responses by attempting re-authentication
-            if (response.status === 401) {
+            // Handle 401/403 responses by attempting re-authentication.
+            // 403 may indicate the server requires a broader scope (upscoping).
+            if (response.status === 401 || response.status === 403) {
                 try {
                     const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
 
                     // Use provided baseUrl or extract from request URL
                     const serverUrl = baseUrl || (typeof input === 'string' ? new URL(input).origin : input.origin);
 
-                    const result = await auth(provider, {
+                    let result = await auth(provider, {
                         serverUrl,
                         resourceMetadataUrl,
                         scope,
                         fetchFn: next
                     });
 
                     if (result === 'REDIRECT') {
-                        throw new UnauthorizedError('Authentication requires user authorization - redirect initiated');
+                        // If the provider can supply the authorization code inline (e.g., a
+                        // headless provider that handles the callback itself), complete the
+                        // token exchange automatically instead of throwing.
+                        if (typeof provider.getAuthorizationCode === 'function') {
+                            const authorizationCode = await provider.getAuthorizationCode();
+                            result = await auth(provider, {
+                                serverUrl,
+                                resourceMetadataUrl,
+                                scope,
+                                authorizationCode,
+                                fetchFn: next
+                            });
+                        } else {
+                            throw new UnauthorizedError('Authentication requires user authorization - redirect initiated');
+                        }
                     }
 
                     if (result !== 'AUTHORIZED') {
@@ -86,8 +101,8 @@ export const withOAuth =
                 }
             }
 
-            // If we still have a 401 after re-auth attempt, throw an error
-            if (response.status === 401) {
+            // If we still have a 401/403 after re-auth attempt, throw an error
+            if (response.status === 401 || response.status === 403) {
                 const url = typeof input === 'string' ? input : input.toString();
                 throw new UnauthorizedError(`Authentication failed for ${url}`);
             }

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

@@ -370,6 +370,128 @@ describe('withOAuth', () => {
             fetchFn: mockFetch
         });
     });
+
+    it('should retry request after successful auth on 403 response', async () => {
+        mockProvider.tokens
+            .mockResolvedValueOnce({
+                access_token: 'old-token',
+                token_type: 'Bearer',
+                expires_in: 3600
+            })
+            .mockResolvedValueOnce({
+                access_token: 'new-token',
+                token_type: 'Bearer',
+                expires_in: 3600
+            });
+
+        const forbiddenResponse = new Response('Forbidden', {
+            status: 403,
+            headers: { 'www-authenticate': 'Bearer realm="oauth" scope="write"' }
+        });
+        const successResponse = new Response('success', { status: 200 });
+
+        mockFetch.mockResolvedValueOnce(forbiddenResponse).mockResolvedValueOnce(successResponse);
+
+        mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'write' });
+        mockAuth.mockResolvedValue('AUTHORIZED');
+
+        const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+        const result = await enhancedFetch('https://api.example.com/data');
+
+        expect(result).toBe(successResponse);
+        expect(mockFetch).toHaveBeenCalledTimes(2);
+        expect(mockAuth).toHaveBeenCalledWith(mockProvider, {
+            serverUrl: 'https://api.example.com',
+            resourceMetadataUrl: undefined,
+            scope: 'write',
+            fetchFn: mockFetch
+        });
+    });
+
+    it('should throw UnauthorizedError on persistent 403 after re-auth', async () => {
+        mockProvider.tokens.mockResolvedValue({
+            access_token: 'test-token',
+            token_type: 'Bearer',
+            expires_in: 3600
+        });
+
+        mockFetch.mockResolvedValue(new Response('Forbidden', { status: 403 }));
+        mockExtractWWWAuthenticateParams.mockReturnValue({});
+        mockAuth.mockResolvedValue('AUTHORIZED');
+
+        const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+        await expect(enhancedFetch('https://api.example.com/data')).rejects.toThrow(
+            'Authentication failed for https://api.example.com/data'
+        );
+
+        expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should complete auth code flow when provider implements getAuthorizationCode', async () => {
+        mockProvider.tokens
+            .mockResolvedValueOnce({
+                access_token: 'old-token',
+                token_type: 'Bearer',
+                expires_in: 3600
+            })
+            .mockResolvedValueOnce({
+                access_token: 'fresh-token',
+                token_type: 'Bearer',
+                expires_in: 3600
+            });
+
+        const unauthorizedResponse = new Response('Unauthorized', { status: 401 });
+        const successResponse = new Response('success', { status: 200 });
+
+        mockFetch.mockResolvedValueOnce(unauthorizedResponse).mockResolvedValueOnce(successResponse);
+
+        mockExtractWWWAuthenticateParams.mockReturnValue({ scope: 'read' });
+        // First auth() call returns REDIRECT; second (with auth code) returns AUTHORIZED
+        mockAuth.mockResolvedValueOnce('REDIRECT').mockResolvedValueOnce('AUTHORIZED');
+
+        // Provider that can supply the authorization code after the redirect
+        const providerWithCode = {
+            ...mockProvider,
+            getAuthorizationCode: vi.fn().mockResolvedValue('auth-code-123')
+        };
+
+        const enhancedFetch = withOAuth(providerWithCode, 'https://api.example.com')(mockFetch);
+
+        const result = await enhancedFetch('https://api.example.com/data');
+
+        expect(result).toBe(successResponse);
+        expect(providerWithCode.getAuthorizationCode).toHaveBeenCalledTimes(1);
+        expect(mockAuth).toHaveBeenCalledTimes(2);
+        // Second auth() call should include the authorization code
+        expect(mockAuth).toHaveBeenNthCalledWith(2, providerWithCode, {
+            serverUrl: 'https://api.example.com',
+            resourceMetadataUrl: undefined,
+            scope: 'read',
+            authorizationCode: 'auth-code-123',
+            fetchFn: mockFetch
+        });
+        expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should throw UnauthorizedError when auth returns REDIRECT and provider has no getAuthorizationCode', async () => {
+        mockProvider.tokens.mockResolvedValue({
+            access_token: 'test-token',
+            token_type: 'Bearer',
+            expires_in: 3600
+        });
+
+        mockFetch.mockResolvedValue(new Response('Unauthorized', { status: 401 }));
+        mockExtractWWWAuthenticateParams.mockReturnValue({});
+        mockAuth.mockResolvedValue('REDIRECT');
+
+        const enhancedFetch = withOAuth(mockProvider, 'https://api.example.com')(mockFetch);
+
+        await expect(enhancedFetch('https://api.example.com/data')).rejects.toThrow(
+            'Authentication requires user authorization - redirect initiated'
+        );
+    });
 });
 
 describe('withLogging', () => {

test/conformance/src/helpers/conformanceOAuthProvider.ts

@@ -73,7 +73,7 @@ export class ConformanceOAuthProvider implements OAuthClientProvider {
         }
     }
 
-    async getAuthCode(): Promise<string> {
+    async getAuthorizationCode(): Promise<string> {
         if (this._authCode) {
             return this._authCode;
         }

test/conformance/src/helpers/withOAuthRetry.ts

@@ -18,15 +18,10 @@ export const handle401 = async (
     });
 
     if (result === 'REDIRECT') {
-        // Ordinarily, we'd wait for the callback to be handled here,
-        // but in our conformance provider, we get the authorization code
-        // during the redirect handling, so we can go straight to
-        // retrying the auth step.
-        // await provider.waitForCallback();
-
-        const authorizationCode = await provider.getAuthCode();
-
-        // TODO: this retry logic should be incorporated into the typescript SDK
+        // The conformance provider captures the authorization code during
+        // redirectToAuthorization(), so we can retrieve it immediately and
+        // complete the token exchange via a second auth() call.
+        const authorizationCode = await provider.getAuthorizationCode();
         result = await auth(provider, {
             serverUrl,
             resourceMetadataUrl,