refactor: adapt OAuthClientProvider at transport boundary (non-breaking)

Alternative to the breaking 'extends AuthProvider' approach. Instead of
requiring OAuthClientProvider implementations to add token() +
onUnauthorized(), the transport constructor classifies the authProvider
option once and adapts OAuth providers via adaptOAuthProvider().

- OAuthClientProvider interface is unchanged from v1
- Transport option: authProvider?: AuthProvider | OAuthClientProvider
- Constructor: if OAuth, store both original (for finishAuth/403) and
  adapted (for _commonHeaders/401) — classification happens once, no
  runtime type guards in the hot path
- 4 built-in providers no longer need token()/onUnauthorized()
- migration.md/migration-SKILL.md entries removed — nothing to migrate
- Changeset downgraded to minor

Net -142 lines vs the breaking approach. Same transport simplification,
zero migration burden. Duck-typing via isOAuthClientProvider()
('tokens' + 'clientMetadata' in provider) at construction only.

Author: felixweinberger

.changeset/token-provider-composable-auth.md

@@ -1,17 +1,16 @@
 ---
-'@modelcontextprotocol/client': major
+'@modelcontextprotocol/client': minor
 ---
 
-Unify client auth around a minimal `AuthProvider` interface
-
-**Breaking:** Transport `authProvider` option now accepts the new minimal `AuthProvider` interface instead of being typed as `OAuthClientProvider`. `OAuthClientProvider` now extends `AuthProvider`, so most existing code continues to work — but custom implementations must add a `token()` method.
+Add `AuthProvider` for composable bearer-token auth; transports adapt `OAuthClientProvider` automatically
 
 - New `AuthProvider` interface: `{ token(): Promise<string | undefined>; onUnauthorized?(ctx): Promise<void> }`. Transports call `token()` before every request and `onUnauthorized()` on 401 (then retry once).
-- `OAuthClientProvider` extends `AuthProvider`. Custom implementations must add `token()` (typically `return (await this.tokens())?.access_token`) and optionally `onUnauthorized()` (typically `return handleOAuthUnauthorized(this, ctx)`).
-- Built-in providers (`ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`, `CrossAppAccessProvider`) implement both methods — existing user code is unchanged.
-- New `handleOAuthUnauthorized(provider, ctx)` helper runs the standard OAuth flow from `onUnauthorized`.
-- New `isOAuthClientProvider()` type guard for gating OAuth-specific transport features like `finishAuth()`.
-- Transports no longer inline OAuth orchestration — ~50 lines of `auth()` calls, WWW-Authenticate parsing, and circuit-breaker state moved into `onUnauthorized()` implementations.
+- Transport `authProvider` option now accepts `AuthProvider | OAuthClientProvider`. OAuth providers are adapted internally via `adaptOAuthProvider()` — no changes needed to existing `OAuthClientProvider` implementations.
+- For simple bearer tokens (API keys, gateway-managed tokens, service accounts): `{ authProvider: { token: async () => myKey } }` — one-line object literal, no class.
+- New `adaptOAuthProvider(provider)` export for explicit adaptation.
+- New `handleOAuthUnauthorized(provider, ctx)` helper — the standard OAuth `onUnauthorized` behavior.
+- New `isOAuthClientProvider()` type guard.
+- New `UnauthorizedContext` type.
 - Exported previously-internal auth helpers for building custom flows: `applyBasicAuth`, `applyPostAuth`, `applyPublicAuth`, `executeTokenRequest`.
 
-See `docs/migration.md` for before/after examples.
+Transports are simplified internally — ~50 lines of inline OAuth orchestration (auth() calls, WWW-Authenticate parsing, circuit-breaker state) moved into the adapter's `onUnauthorized()` implementation. `OAuthClientProvider` itself is unchanged.

docs/migration-SKILL.md

@@ -203,39 +203,6 @@ import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/core';
 if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient) { ... }
 ```
 
-### Client `OAuthClientProvider` now extends `AuthProvider`
-
-Transport `authProvider` options now accept the minimal `AuthProvider` interface. `OAuthClientProvider` extends it, so built-in providers work unchanged — custom implementations must add `token()`.
-
-| v1 pattern                                            | v2 equivalent                                                               |
-| ----------------------------------------------------- | --------------------------------------------------------------------------- |
-| `authProvider?: OAuthClientProvider` (option type)    | `authProvider?: AuthProvider` (accepts `OAuthClientProvider` via extension) |
-| Transport reads `authProvider.tokens()?.access_token` | Transport calls `authProvider.token()`                                      |
-| Transport inlines `auth()` on 401                     | Transport calls `authProvider.onUnauthorized()` then retries once           |
-| `_hasCompletedAuthFlow` circuit breaker               | `_authRetryInFlight` circuit breaker                                        |
-| N/A                                                   | `handleOAuthUnauthorized(provider, ctx)` — standard `onUnauthorized` impl   |
-| N/A                                                   | `isOAuthClientProvider(provider)` — type guard                              |
-| N/A                                                   | `UnauthorizedContext` — `{ response, serverUrl, fetchFn }`                  |
-
-**For custom `OAuthClientProvider` implementations**, add both methods (both required — TypeScript enforces this):
-
-```typescript
-async token(): Promise<string | undefined> {
-    return (await this.tokens())?.access_token;
-}
-
-async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-    await handleOAuthUnauthorized(this, ctx);
-}
-```
-
-**For simple bearer tokens** (previously required stubbing 8 `OAuthClientProvider` members):
-
-```typescript
-// v2: one-liner
-const authProvider: AuthProvider = { token: async () => process.env.API_KEY };
-```
-
 **Unchanged APIs** (only import paths changed): `Client` constructor and most methods, `McpServer` constructor, `server.connect()`, `server.close()`, all client transports (`StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport`), `StdioServerTransport`, all
 Zod schemas, all callback return types. Note: `callTool()` and `request()` signatures changed (schema parameter removed, see section 11).
 

docs/migration.md

@@ -648,44 +648,6 @@ The new design:
 - `ProtocolError` with `ProtocolErrorCode`: For errors that are serialized and sent as JSON-RPC error responses
 - `SdkError` with `SdkErrorCode`: For local errors that are thrown/rejected locally and never leave the SDK
 
-### Client `authProvider` unified around `AuthProvider`
-
-Transport `authProvider` options now accept the minimal `AuthProvider` interface rather than being typed as `OAuthClientProvider`. `OAuthClientProvider` extends `AuthProvider`, so built-in providers and most existing code continue to work unchanged — but custom
-`OAuthClientProvider` implementations must add a `token()` method.
-
-**What changed:** transports now call `authProvider.token()` before every request (instead of `authProvider.tokens()?.access_token`), and call `authProvider.onUnauthorized()` on 401 (instead of inlining OAuth orchestration). One code path handles both simple bearer tokens and
-full OAuth.
-
-**If you implement `OAuthClientProvider` directly** (the interactive browser-redirect pattern), add:
-
-```ts
-class MyProvider implements OAuthClientProvider {
-    // ...existing 8 required members...
-
-    // Required: return the current access token
-    async token(): Promise<string | undefined> {
-        return (await this.tokens())?.access_token;
-    }
-
-    // Required: runs the OAuth flow on 401 — without this, 401 throws with no recovery
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-}
-```
-
-**If you use `ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`, or `CrossAppAccessProvider`** — no change. These already implement both methods.
-
-**If you have simple bearer tokens** (API keys, gateway tokens, externally-managed tokens), you can now skip `OAuthClientProvider` entirely:
-
-```ts
-// Before: had to implement 8 OAuthClientProvider members with no-op stubs
-// After:
-const transport = new StreamableHTTPClientTransport(url, {
-    authProvider: { token: async () => process.env.API_KEY }
-});
-```
-
 ### OAuth error refactoring
 
 The OAuth error classes have been consolidated into a single `OAuthError` class with an `OAuthErrorCode` enum.

examples/client/src/simpleOAuthClientProvider.ts

@@ -1,11 +1,4 @@
-import type {
-    OAuthClientInformationMixed,
-    OAuthClientMetadata,
-    OAuthClientProvider,
-    OAuthTokens,
-    UnauthorizedContext
-} from '@modelcontextprotocol/client';
-import { handleOAuthUnauthorized } from '@modelcontextprotocol/client';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from '@modelcontextprotocol/client';
 
 /**
  * In-memory OAuth client provider for demonstration purposes
@@ -31,14 +24,6 @@ export class InMemoryOAuthClientProvider implements OAuthClientProvider {
 
     private _onRedirect: (url: URL) => void;
 
-    async token(): Promise<string | undefined> {
-        return this._tokens?.access_token;
-    }
-
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-
     get redirectUrl(): string | URL {
         return this._redirectUrl;
     }

packages/client/src/client/auth.examples.ts

@@ -9,8 +9,8 @@
 
 import type { AuthorizationServerMetadata } from '@modelcontextprotocol/core';
 
-import type { OAuthClientProvider, UnauthorizedContext } from './auth.js';
-import { fetchToken, handleOAuthUnauthorized } from './auth.js';
+import type { OAuthClientProvider } from './auth.js';
+import { fetchToken } from './auth.js';
 
 /**
  * Base class providing no-op implementations of required OAuthClientProvider methods.
@@ -29,12 +29,6 @@ abstract class MyProviderBase implements OAuthClientProvider {
     tokens(): undefined {
         return;
     }
-    async token(): Promise<string | undefined> {
-        return undefined;
-    }
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
     saveTokens() {
         return Promise.resolve();
     }

packages/client/src/client/auth.ts

@@ -60,8 +60,8 @@ export interface UnauthorizedContext {
  * const authProvider: AuthProvider = { token: async () => process.env.API_KEY };
  * ```
  *
- * For OAuth flows, use {@linkcode OAuthClientProvider} which extends this interface,
- * or one of the built-in providers ({@linkcode index.ClientCredentialsProvider | ClientCredentialsProvider} etc.).
+ * For OAuth flows, pass an {@linkcode OAuthClientProvider} directly — transports
+ * accept either shape and adapt OAuth providers automatically via {@linkcode adaptOAuthProvider}.
  */
 export interface AuthProvider {
     /**
@@ -82,19 +82,17 @@ export interface AuthProvider {
 }
 
 /**
- * Type guard: checks whether an `AuthProvider` is a full `OAuthClientProvider`.
- * Use this to gate OAuth-specific transport features like `finishAuth()` and
- * 403 scope upscoping.
+ * Type guard distinguishing `OAuthClientProvider` from a minimal `AuthProvider`.
+ * Transports use this at construction time to classify the `authProvider` option.
  */
-export function isOAuthClientProvider(provider: AuthProvider | undefined): provider is OAuthClientProvider {
+export function isOAuthClientProvider(provider: AuthProvider | OAuthClientProvider | undefined): provider is OAuthClientProvider {
     return provider !== undefined && 'tokens' in provider && 'clientMetadata' in provider;
 }
 
 /**
- * Default `onUnauthorized` implementation for OAuth providers: extracts
+ * Standard `onUnauthorized` behavior for OAuth providers: extracts
  * `WWW-Authenticate` parameters from the 401 response and runs {@linkcode auth}.
- * Built-in providers ({@linkcode index.ClientCredentialsProvider | ClientCredentialsProvider} etc.)
- * delegate to this. Custom `OAuthClientProvider` implementations can do the same.
+ * Used by {@linkcode adaptOAuthProvider} to bridge `OAuthClientProvider` to `AuthProvider`.
  */
 export async function handleOAuthUnauthorized(provider: OAuthClientProvider, ctx: UnauthorizedContext): Promise<void> {
     const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(ctx.response);
@@ -109,28 +107,34 @@ export async function handleOAuthUnauthorized(provider: OAuthClientProvider, ctx
     }
 }
 
+/**
+ * Adapts an `OAuthClientProvider` to the minimal `AuthProvider` interface that
+ * transports consume. Called once at transport construction — the transport stores
+ * the adapted provider for `_commonHeaders()` and 401 handling, while keeping the
+ * original `OAuthClientProvider` for OAuth-specific paths (`finishAuth()`, 403 upscoping).
+ */
+export function adaptOAuthProvider(provider: OAuthClientProvider): AuthProvider {
+    return {
+        token: async () => {
+            const tokens = await provider.tokens();
+            return tokens?.access_token;
+        },
+        onUnauthorized: async ctx => handleOAuthUnauthorized(provider, ctx)
+    };
+}
+
 /**
  * Implements an end-to-end OAuth client to be used with one MCP server.
  *
  * This client relies upon a concept of an authorized "session," the exact
  * meaning of which is application-defined. Tokens, authorization codes, and
  * code verifiers should not cross different sessions.
  *
- * Extends {@linkcode AuthProvider} — implementations must provide `token()`
- * (typically `return (await this.tokens())?.access_token`) and `onUnauthorized()`
- * (typically `return handleOAuthUnauthorized(this, ctx)`). Without `onUnauthorized()`,
- * 401 responses throw immediately with no token refresh or reauth.
+ * Transports accept `OAuthClientProvider` directly via the `authProvider` option —
+ * they adapt it to {@linkcode AuthProvider} internally via {@linkcode adaptOAuthProvider}.
+ * No changes are needed to existing implementations.
  */
-export interface OAuthClientProvider extends AuthProvider {
-    /**
-     * Runs the OAuth re-authentication flow on 401. Required on `OAuthClientProvider`
-     * (optional on the base `AuthProvider`) because OAuth providers that omit this lose
-     * all 401 recovery — no token refresh, no redirect to authorization.
-     *
-     * Most implementations should delegate: `return handleOAuthUnauthorized(this, ctx)`.
-     */
-    onUnauthorized(ctx: UnauthorizedContext): Promise<void>;
-
+export interface OAuthClientProvider {
     /**
      * The URL to redirect the user agent to after authorization.
      * Return `undefined` for non-interactive flows that don't require user interaction

packages/client/src/client/authExtensions.ts

@@ -8,8 +8,7 @@
 import type { FetchLike, OAuthClientInformation, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/core';
 import type { CryptoKey, JWK } from 'jose';
 
-import type { AddClientAuthentication, OAuthClientProvider, UnauthorizedContext } from './auth.js';
-import { handleOAuthUnauthorized } from './auth.js';
+import type { AddClientAuthentication, OAuthClientProvider } from './auth.js';
 
 /**
  * Helper to produce a `private_key_jwt` client authentication function.
@@ -151,14 +150,6 @@ export class ClientCredentialsProvider implements OAuthClientProvider {
         };
     }
 
-    async token(): Promise<string | undefined> {
-        return this._tokens?.access_token;
-    }
-
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-
     get redirectUrl(): undefined {
         return undefined;
     }
@@ -278,14 +269,6 @@ export class PrivateKeyJwtProvider implements OAuthClientProvider {
         });
     }
 
-    async token(): Promise<string | undefined> {
-        return this._tokens?.access_token;
-    }
-
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-
     get redirectUrl(): undefined {
         return undefined;
     }
@@ -383,14 +366,6 @@ export class StaticPrivateKeyJwtProvider implements OAuthClientProvider {
         };
     }
 
-    async token(): Promise<string | undefined> {
-        return this._tokens?.access_token;
-    }
-
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-
     get redirectUrl(): undefined {
         return undefined;
     }
@@ -589,14 +564,6 @@ export class CrossAppAccessProvider implements OAuthClientProvider {
         this._fetchFn = options.fetchFn ?? fetch;
     }
 
-    async token(): Promise<string | undefined> {
-        return this._tokens?.access_token;
-    }
-
-    async onUnauthorized(ctx: UnauthorizedContext): Promise<void> {
-        await handleOAuthUnauthorized(this, ctx);
-    }
-
     get redirectUrl(): undefined {
         return undefined;
     }

packages/client/src/client/sse.ts

@@ -3,8 +3,8 @@ import { createFetchWithInit, JSONRPCMessageSchema, normalizeHeaders, SdkError,
 import type { ErrorEvent, EventSourceInit } from 'eventsource';
 import { EventSource } from 'eventsource';
 
-import type { AuthProvider } from './auth.js';
-import { auth, extractWWWAuthenticateParams, isOAuthClientProvider, UnauthorizedError } from './auth.js';
+import type { AuthProvider, OAuthClientProvider } from './auth.js';
+import { adaptOAuthProvider, auth, extractWWWAuthenticateParams, isOAuthClientProvider, UnauthorizedError } from './auth.js';
 
 export class SseError extends Error {
     constructor(
@@ -35,7 +35,7 @@ export type SSEClientTransportOptions = {
      * Interactive flows: after {@linkcode UnauthorizedError}, redirect the user, then call
      * {@linkcode SSEClientTransport.finishAuth | finishAuth} with the authorization code before reconnecting.
      */
-    authProvider?: AuthProvider;
+    authProvider?: AuthProvider | OAuthClientProvider;
 
     /**
      * Customizes the initial SSE request to the server (the request that begins the stream).
@@ -73,6 +73,7 @@ export class SSEClientTransport implements Transport {
     private _eventSourceInit?: EventSourceInit;
     private _requestInit?: RequestInit;
     private _authProvider?: AuthProvider;
+    private _oauthProvider?: OAuthClientProvider;
     private _fetch?: FetchLike;
     private _fetchWithInit: FetchLike;
     private _protocolVersion?: string;
@@ -87,7 +88,12 @@ export class SSEClientTransport implements Transport {
         this._scope = undefined;
         this._eventSourceInit = opts?.eventSourceInit;
         this._requestInit = opts?.requestInit;
-        this._authProvider = opts?.authProvider;
+        if (isOAuthClientProvider(opts?.authProvider)) {
+            this._oauthProvider = opts.authProvider;
+            this._authProvider = adaptOAuthProvider(opts.authProvider);
+        } else {
+            this._authProvider = opts?.authProvider;
+        }
         this._fetch = opts?.fetch;
         this._fetchWithInit = createFetchWithInit(opts?.fetch, opts?.requestInit);
     }
@@ -215,11 +221,11 @@ export class SSEClientTransport implements Transport {
      * Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.
      */
     async finishAuth(authorizationCode: string): Promise<void> {
-        if (!isOAuthClientProvider(this._authProvider)) {
+        if (!this._oauthProvider) {
             throw new UnauthorizedError('finishAuth requires an OAuthClientProvider');
         }
 
-        const result = await auth(this._authProvider, {
+        const result = await auth(this._oauthProvider, {
             serverUrl: this._url,
             authorizationCode,
             resourceMetadataUrl: this._resourceMetadataUrl,