BREAKING: unify client auth around minimal AuthProvider interface

Transports now accept AuthProvider { token(), onUnauthorized?() } instead
of being typed as OAuthClientProvider. OAuthClientProvider extends
AuthProvider, so built-in providers work unchanged — but custom
implementations must add token().

Key changes:
- New AuthProvider interface in auth.ts — transports only need token()
  + optional onUnauthorized(), not the full 21-member OAuth interface
- OAuthClientProvider extends AuthProvider; the 4 built-in providers
  implement token() + onUnauthorized() (delegating to new
  handleOAuthUnauthorized helper)
- Transports call authProvider.token() in _commonHeaders() — one code
  path, no precedence rules
- Transports call authProvider.onUnauthorized() on 401, retry once —
  ~50 lines of inline OAuth orchestration removed per transport
- finishAuth() and 403 upscoping gated on isOAuthClientProvider() guard
- TokenProvider type + tokenProvider option deleted — subsumed by
  { token: async () => ... } as authProvider

See migration.md for before/after. This is an alternative design
presented for discussion alongside the additive approach in the
earlier commits — the team should pick one shape before merge.

Author: felixweinberger

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

@@ -1,10 +1,17 @@
 ---
-'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/client': major
 ---
 
-Add `TokenProvider` for simple bearer-token authentication and export composable auth primitives
+Unify client auth around a minimal `AuthProvider` interface
 
-- New `TokenProvider` type — a minimal `() => Promise<string | undefined>` function interface for supplying bearer tokens. Use this instead of `OAuthClientProvider` when tokens are managed externally (gateway/proxy patterns, service accounts, upfront API tokens, or any scenario where the full OAuth redirect flow is not needed).
-- New `tokenProvider` option on `StreamableHTTPClientTransport` and `SSEClientTransport`. Called before every request to obtain a fresh token. If both `authProvider` and `tokenProvider` are set, `authProvider` takes precedence.
-- New `withBearerAuth(getToken, fetchFn?)` helper that wraps a fetch function to inject `Authorization: Bearer` headers — useful for composing with other fetch middleware.
-- Exported previously-internal auth helpers for building custom auth flows: `applyBasicAuth`, `applyPostAuth`, `applyPublicAuth`, `executeTokenRequest`.
+**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.
+
+- 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.
+- Exported previously-internal auth helpers for building custom flows: `applyBasicAuth`, `applyPostAuth`, `applyPublicAuth`, `executeTokenRequest`.
+
+See `docs/migration.md` for before/after examples.

docs/client.md

@@ -13,7 +13,7 @@ A client connects to a server, discovers what it offers — tools, resources, pr
 The examples below use these imports. Adjust based on which features and transport you need:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#imports"
-import type { Prompt, Resource, TokenProvider, Tool } from '@modelcontextprotocol/client';
+import type { AuthProvider, Prompt, Resource, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
     Client,
@@ -113,19 +113,19 @@ console.log(systemPrompt);
 
 ## Authentication
 
-MCP servers can require authentication before accepting client connections (see [Authorization](https://modelcontextprotocol.io/specification/latest/basic/authorization) in the MCP specification). For servers that accept plain bearer tokens, pass a `tokenProvider` function to {@linkcode @modelcontextprotocol/client!client/streamableHttp.StreamableHTTPClientTransport | StreamableHTTPClientTransport}. For servers that require OAuth 2.0, pass an `authProvider` — the SDK provides built-in providers for common machine-to-machine flows, or you can implement the full {@linkcode @modelcontextprotocol/client!client/auth.OAuthClientProvider | OAuthClientProvider} interface for user-facing OAuth.
+MCP servers can require authentication before accepting client connections (see [Authorization](https://modelcontextprotocol.io/specification/latest/basic/authorization) in the MCP specification). Pass an {@linkcode @modelcontextprotocol/client!client/auth.AuthProvider | AuthProvider} to {@linkcode @modelcontextprotocol/client!client/streamableHttp.StreamableHTTPClientTransport | StreamableHTTPClientTransport}. The transport calls `token()` before every request and `onUnauthorized()` (if provided) on 401, then retries once.
 
-### Token provider
+### Bearer tokens
 
-For servers that accept bearer tokens managed outside the SDK — API keys, tokens from a gateway or proxy, service-account credentials, or tokens obtained through a separate auth flow — pass a {@linkcode @modelcontextprotocol/client!client/tokenProvider.TokenProvider | TokenProvider} function. It is called before every request, so it can handle expiry and refresh internally. If the server rejects the token with 401, the transport throws {@linkcode @modelcontextprotocol/client!client/auth.UnauthorizedError | UnauthorizedError} without retrying — catch it to invalidate any external cache and reconnect:
+For servers that accept bearer tokens managed outside the SDK — API keys, tokens from a gateway or proxy, service-account credentials — implement only `token()`. With no `onUnauthorized()`, a 401 throws {@linkcode @modelcontextprotocol/client!client/auth.UnauthorizedError | UnauthorizedError} immediately:
 
 ```ts source="../examples/client/src/clientGuide.examples.ts#auth_tokenProvider"
-const tokenProvider: TokenProvider = async () => getStoredToken();
+const authProvider: AuthProvider = { token: async () => getStoredToken() };
 
-const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { tokenProvider });
+const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { authProvider });
 ```
 
-See [`simpleTokenProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleTokenProvider.ts) for a complete runnable example. For finer control, {@linkcode @modelcontextprotocol/client!client/tokenProvider.withBearerAuth | withBearerAuth} wraps a fetch function directly.
+See [`simpleTokenProvider.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleTokenProvider.ts) for a complete runnable example.
 
 ### Client credentials
 

docs/migration.md

@@ -252,6 +252,7 @@ server.registerTool('ping', {
 ```
 
 This applies to:
+
 - `inputSchema` in `registerTool()`
 - `outputSchema` in `registerTool()`
 - `argsSchema` in `registerPrompt()`
@@ -339,25 +340,21 @@ Common method string replacements:
 
 ### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
 
-The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
+The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas
+like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
 
 **`client.request()` — Before (v1):**
 
 ```typescript
 import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
 
-const result = await client.request(
-    { method: 'tools/call', params: { name: 'my-tool', arguments: {} } },
-    CallToolResultSchema
-);
+const result = await client.request({ method: 'tools/call', params: { name: 'my-tool', arguments: {} } }, CallToolResultSchema);
 ```
 
 **After (v2):**
 
 ```typescript
-const result = await client.request(
-    { method: 'tools/call', params: { name: 'my-tool', arguments: {} } }
-);
+const result = await client.request({ method: 'tools/call', params: { name: 'my-tool', arguments: {} } });
 ```
 
 **`ctx.mcpReq.send()` — Before (v1):**
@@ -390,10 +387,7 @@ server.setRequestHandler('tools/call', async (request, ctx) => {
 ```typescript
 import { CompatibilityCallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
 
-const result = await client.callTool(
-    { name: 'my-tool', arguments: {} },
-    CompatibilityCallToolResultSchema
-);
+const result = await client.callTool({ name: 'my-tool', arguments: {} }, CompatibilityCallToolResultSchema);
 ```
 
 **After (v2):**
@@ -452,43 +446,43 @@ import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse
 
 The `RequestHandlerExtra` type has been replaced with a structured context type hierarchy using nested groups:
 
-| v1 | v2 |
-|----|-----|
+| v1                                       | v2                                                                     |
+| ---------------------------------------- | ---------------------------------------------------------------------- |
 | `RequestHandlerExtra` (flat, all fields) | `ServerContext` (server handlers) or `ClientContext` (client handlers) |
-| `extra` parameter name | `ctx` parameter name |
-| `extra.signal` | `ctx.mcpReq.signal` |
-| `extra.requestId` | `ctx.mcpReq.id` |
-| `extra._meta` | `ctx.mcpReq._meta` |
-| `extra.sendRequest(...)` | `ctx.mcpReq.send(...)` |
-| `extra.sendNotification(...)` | `ctx.mcpReq.notify(...)` |
-| `extra.authInfo` | `ctx.http?.authInfo` |
-| `extra.requestInfo` | `ctx.http?.req` (only on `ServerContext`) |
-| `extra.closeSSEStream` | `ctx.http?.closeSSE` (only on `ServerContext`) |
-| `extra.closeStandaloneSSEStream` | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`) |
-| `extra.sessionId` | `ctx.sessionId` |
-| `extra.taskStore` | `ctx.task?.store` |
-| `extra.taskId` | `ctx.task?.id` |
-| `extra.taskRequestedTtl` | `ctx.task?.requestedTtl` |
+| `extra` parameter name                   | `ctx` parameter name                                                   |
+| `extra.signal`                           | `ctx.mcpReq.signal`                                                    |
+| `extra.requestId`                        | `ctx.mcpReq.id`                                                        |
+| `extra._meta`                            | `ctx.mcpReq._meta`                                                     |
+| `extra.sendRequest(...)`                 | `ctx.mcpReq.send(...)`                                                 |
+| `extra.sendNotification(...)`            | `ctx.mcpReq.notify(...)`                                               |
+| `extra.authInfo`                         | `ctx.http?.authInfo`                                                   |
+| `extra.requestInfo`                      | `ctx.http?.req` (only on `ServerContext`)                              |
+| `extra.closeSSEStream`                   | `ctx.http?.closeSSE` (only on `ServerContext`)                         |
+| `extra.closeStandaloneSSEStream`         | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`)               |
+| `extra.sessionId`                        | `ctx.sessionId`                                                        |
+| `extra.taskStore`                        | `ctx.task?.store`                                                      |
+| `extra.taskId`                           | `ctx.task?.id`                                                         |
+| `extra.taskRequestedTtl`                 | `ctx.task?.requestedTtl`                                               |
 
 **Before (v1):**
 
 ```typescript
 server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-  const headers = extra.requestInfo?.headers;
-  const taskStore = extra.taskStore;
-  await extra.sendNotification({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
-  return { content: [{ type: 'text', text: 'result' }] };
+    const headers = extra.requestInfo?.headers;
+    const taskStore = extra.taskStore;
+    await extra.sendNotification({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
+    return { content: [{ type: 'text', text: 'result' }] };
 });
 ```
 
 **After (v2):**
 
 ```typescript
 server.setRequestHandler('tools/call', async (request, ctx) => {
-  const headers = ctx.http?.req?.headers;
-  const taskStore = ctx.task?.store;
-  await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
-  return { content: [{ type: 'text', text: 'result' }] };
+    const headers = ctx.http?.req?.headers;
+    const taskStore = ctx.task?.store;
+    await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
+    return { content: [{ type: 'text', text: 'result' }] };
 });
 ```
 
@@ -504,22 +498,22 @@ Context fields are organized into 4 groups:
 
 ```typescript
 server.setRequestHandler('tools/call', async (request, ctx) => {
-  // Send a log message (respects client's log level filter)
-  await ctx.mcpReq.log('info', 'Processing tool call', 'my-logger');
-
-  // Request client to sample an LLM
-  const samplingResult = await ctx.mcpReq.requestSampling({
-    messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],
-    maxTokens: 100,
-  });
-
-  // Elicit user input via a form
-  const elicitResult = await ctx.mcpReq.elicitInput({
-    message: 'Please provide details',
-    requestedSchema: { type: 'object', properties: { name: { type: 'string' } } },
-  });
-
-  return { content: [{ type: 'text', text: 'done' }] };
+    // Send a log message (respects client's log level filter)
+    await ctx.mcpReq.log('info', 'Processing tool call', 'my-logger');
+
+    // Request client to sample an LLM
+    const samplingResult = await ctx.mcpReq.requestSampling({
+        messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],
+        maxTokens: 100
+    });
+
+    // Elicit user input via a form
+    const elicitResult = await ctx.mcpReq.elicitInput({
+        message: 'Please provide details',
+        requestedSchema: { type: 'object', properties: { name: { type: 'string' } } }
+    });
+
+    return { content: [{ type: 'text', text: 'done' }] };
 });
 ```
 
@@ -646,13 +640,52 @@ try {
 
 #### Why this change?
 
-Previously, `ErrorCode.RequestTimeout` (-32001) and `ErrorCode.ConnectionClosed` (-32000) were used for local timeout/connection errors. However, these errors never cross the wire as JSON-RPC responses - they are rejected locally. Using protocol error codes for local errors was semantically inconsistent.
+Previously, `ErrorCode.RequestTimeout` (-32001) and `ErrorCode.ConnectionClosed` (-32000) were used for local timeout/connection errors. However, these errors never cross the wire as JSON-RPC responses - they are rejected locally. Using protocol error codes for local errors was
+semantically inconsistent.
 
 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;
+    }
+
+    // Optional but recommended: runs the OAuth flow on 401
+    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.
@@ -743,11 +776,11 @@ This means Cloudflare Workers users no longer need to explicitly pass the valida
 import { McpServer, CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server';
 
 const server = new McpServer(
-  { name: 'my-server', version: '1.0.0' },
-  {
-    capabilities: { tools: {} },
-    jsonSchemaValidator: new CfWorkerJsonSchemaValidator() // Required in v1
-  }
+    { name: 'my-server', version: '1.0.0' },
+    {
+        capabilities: { tools: {} },
+        jsonSchemaValidator: new CfWorkerJsonSchemaValidator() // Required in v1
+    }
 );
 ```
 
@@ -757,9 +790,9 @@ const server = new McpServer(
 import { McpServer } from '@modelcontextprotocol/server';
 
 const server = new McpServer(
-  { name: 'my-server', version: '1.0.0' },
-  { capabilities: { tools: {} } }
-  // Validator auto-selected based on runtime
+    { name: 'my-server', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+    // Validator auto-selected based on runtime
 );
 ```
 

examples/client/src/clientGuide.examples.ts

@@ -8,7 +8,7 @@
  */
 
 //#region imports
-import type { Prompt, Resource, TokenProvider, Tool } from '@modelcontextprotocol/client';
+import type { AuthProvider, Prompt, Resource, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
     Client,
@@ -107,12 +107,12 @@ async function serverInstructions_basic(client: Client) {
 // Authentication
 // ---------------------------------------------------------------------------
 
-/** Example: TokenProvider for bearer auth with externally-managed tokens. */
+/** Example: Minimal AuthProvider for bearer auth with externally-managed tokens. */
 async function auth_tokenProvider(getStoredToken: () => Promise<string>) {
     //#region auth_tokenProvider
-    const tokenProvider: TokenProvider = async () => getStoredToken();
+    const authProvider: AuthProvider = { token: async () => getStoredToken() };
 
-    const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { tokenProvider });
+    const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { authProvider });
     //#endregion auth_tokenProvider
     return transport;
 }

examples/client/src/simpleOAuthClientProvider.ts

@@ -1,4 +1,11 @@
-import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from '@modelcontextprotocol/client';
+import type {
+    OAuthClientInformationMixed,
+    OAuthClientMetadata,
+    OAuthClientProvider,
+    OAuthTokens,
+    UnauthorizedContext
+} from '@modelcontextprotocol/client';
+import { handleOAuthUnauthorized } from '@modelcontextprotocol/client';
 
 /**
  * In-memory OAuth client provider for demonstration purposes
@@ -24,6 +31,14 @@ 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;
     }