feat: add TokenProvider for composable bearer-token auth (non-breaking)

Adds a minimal `() => Promise<string | undefined>` function type as a
lightweight alternative to OAuthClientProvider, for scenarios where
bearer tokens are managed externally (gateway/proxy patterns, service
accounts, API keys).

- New TokenProvider type + withBearerAuth(getToken, fetchFn?) helper
- New tokenProvider option on StreamableHTTPClientTransport and
  SSEClientTransport, used as fallback after authProvider in
  _commonHeaders(). authProvider takes precedence when both set.
- On 401 with tokenProvider (no authProvider), transports throw
  UnauthorizedError — no retry, since tokenProvider() is already
  called before every request and would likely return the same
  rejected token. Callers catch UnauthorizedError, invalidate
  external cache, reconnect.
- Exported previously-internal auth helpers for building custom
  flows: applyBasicAuth, applyPostAuth, applyPublicAuth,
  executeTokenRequest.
- Tests, example, docs, changeset.

Zero breakage. Bughunter fleet review: 28 findings submitted,
2 confirmed, both addressed.

Author: felixweinberger

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

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add `TokenProvider` for simple bearer-token authentication and export composable auth primitives
+
+- 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`.

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, Tool } from '@modelcontextprotocol/client';
+import type { Prompt, Resource, TokenProvider, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
     Client,
@@ -113,7 +113,19 @@ console.log(systemPrompt);
 
 ## Authentication
 
-MCP servers can require OAuth 2.0 authentication before accepting client connections (see [Authorization](https://modelcontextprotocol.io/specification/latest/basic/authorization) in the MCP specification). Pass an `authProvider` to {@linkcode @modelcontextprotocol/client!client/streamableHttp.StreamableHTTPClientTransport | StreamableHTTPClientTransport} to enable this — 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). 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.
+
+### Token provider
+
+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:
+
+```ts source="../examples/client/src/clientGuide.examples.ts#auth_tokenProvider"
+const tokenProvider: TokenProvider = async () => getStoredToken();
+
+const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { tokenProvider });
+```
+
+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.
 
 ### Client credentials
 

examples/client/src/clientGuide.examples.ts

@@ -8,7 +8,7 @@
  */
 
 //#region imports
-import type { Prompt, Resource, Tool } from '@modelcontextprotocol/client';
+import type { Prompt, Resource, TokenProvider, Tool } from '@modelcontextprotocol/client';
 import {
     applyMiddlewares,
     Client,
@@ -107,6 +107,16 @@ async function serverInstructions_basic(client: Client) {
 // Authentication
 // ---------------------------------------------------------------------------
 
+/** Example: TokenProvider for bearer auth with externally-managed tokens. */
+async function auth_tokenProvider(getStoredToken: () => Promise<string>) {
+    //#region auth_tokenProvider
+    const tokenProvider: TokenProvider = async () => getStoredToken();
+
+    const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'), { tokenProvider });
+    //#endregion auth_tokenProvider
+    return transport;
+}
+
 /** Example: Client credentials auth for service-to-service communication. */
 async function auth_clientCredentials() {
     //#region auth_clientCredentials
@@ -540,6 +550,7 @@ void connect_stdio;
 void connect_sseFallback;
 void disconnect_streamableHttp;
 void serverInstructions_basic;
+void auth_tokenProvider;
 void auth_clientCredentials;
 void auth_privateKeyJwt;
 void auth_crossAppAccess;

examples/client/src/simpleTokenProvider.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Example demonstrating TokenProvider for simple bearer token authentication.
+ *
+ * TokenProvider is a lightweight alternative to OAuthClientProvider for cases
+ * where tokens are managed externally — e.g., pre-configured API tokens,
+ * gateway/proxy patterns, or tokens obtained through a separate auth flow.
+ *
+ * Environment variables:
+ *   MCP_SERVER_URL - Server URL (default: http://localhost:3000/mcp)
+ *   MCP_TOKEN      - Bearer token to use for authentication (required)
+ *
+ * Two approaches are demonstrated:
+ *   1. Using `tokenProvider` option on the transport (simplest)
+ *   2. Using `withBearerAuth` to wrap a custom fetch function (more flexible)
+ */
+
+import type { TokenProvider } from '@modelcontextprotocol/client';
+import { Client, StreamableHTTPClientTransport, withBearerAuth } from '@modelcontextprotocol/client';
+
+const DEFAULT_SERVER_URL = process.env.MCP_SERVER_URL || 'http://localhost:3000/mcp';
+
+async function main() {
+    const token = process.env.MCP_TOKEN;
+    if (!token) {
+        console.error('MCP_TOKEN environment variable is required');
+        process.exit(1);
+    }
+
+    // A TokenProvider is just an async function that returns a token string.
+    // It is called before every request, so it can handle refresh logic internally.
+    const tokenProvider: TokenProvider = async () => token;
+
+    const client = new Client({ name: 'token-provider-example', version: '1.0.0' }, { capabilities: {} });
+
+    // Approach 1: Pass tokenProvider directly to the transport.
+    // This is the simplest way to add bearer auth.
+    const transport = new StreamableHTTPClientTransport(new URL(DEFAULT_SERVER_URL), {
+        tokenProvider
+    });
+
+    // Approach 2 (alternative): Use withBearerAuth to wrap fetch.
+    // This is useful when you need more control over the fetch behavior,
+    // or when composing with other fetch wrappers.
+    //
+    // const transport = new StreamableHTTPClientTransport(new URL(DEFAULT_SERVER_URL), {
+    //     fetch: withBearerAuth(tokenProvider),
+    // });
+
+    await client.connect(transport);
+    console.log('Connected successfully.');
+
+    const tools = await client.listTools();
+    console.log('Available tools:', tools.tools.map(t => t.name).join(', ') || '(none)');
+
+    await transport.close();
+}
+
+try {
+    await main();
+} catch (error) {
+    console.error('Error running client:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
+}
+
+// Referenced in the commented-out Approach 2 above; kept so uncommenting it type-checks.
+void withBearerAuth;

packages/client/src/client/auth.ts

@@ -381,7 +381,7 @@ export function applyClientAuthentication(
 /**
  * Applies HTTP Basic authentication (RFC 6749 Section 2.3.1)
  */
-function applyBasicAuth(clientId: string, clientSecret: string | undefined, headers: Headers): void {
+export function applyBasicAuth(clientId: string, clientSecret: string | undefined, headers: Headers): void {
     if (!clientSecret) {
         throw new Error('client_secret_basic authentication requires a client_secret');
     }
@@ -393,7 +393,7 @@ function applyBasicAuth(clientId: string, clientSecret: string | undefined, head
 /**
  * Applies POST body authentication (RFC 6749 Section 2.3.1)
  */
-function applyPostAuth(clientId: string, clientSecret: string | undefined, params: URLSearchParams): void {
+export function applyPostAuth(clientId: string, clientSecret: string | undefined, params: URLSearchParams): void {
     params.set('client_id', clientId);
     if (clientSecret) {
         params.set('client_secret', clientSecret);
@@ -403,7 +403,7 @@ function applyPostAuth(clientId: string, clientSecret: string | undefined, param
 /**
  * Applies public client authentication (RFC 6749 Section 2.1)
  */
-function applyPublicAuth(clientId: string, params: URLSearchParams): void {
+export function applyPublicAuth(clientId: string, params: URLSearchParams): void {
     params.set('client_id', clientId);
 }
 
@@ -1265,7 +1265,7 @@ export function prepareAuthorizationCodeRequest(
  * Internal helper to execute a token request with the given parameters.
  * Used by {@linkcode exchangeAuthorization}, {@linkcode refreshAuthorization}, and {@linkcode fetchToken}.
  */
-async function executeTokenRequest(
+export async function executeTokenRequest(
     authorizationServerUrl: string | URL,
     {
         metadata,

packages/client/src/client/sse.ts

@@ -5,6 +5,7 @@ import { EventSource } from 'eventsource';
 
 import type { AuthResult, OAuthClientProvider } from './auth.js';
 import { auth, extractWWWAuthenticateParams, UnauthorizedError } from './auth.js';
+import type { TokenProvider } from './tokenProvider.js';
 
 export class SseError extends Error {
     constructor(
@@ -36,6 +37,16 @@ export type SSEClientTransportOptions = {
      */
     authProvider?: OAuthClientProvider;
 
+    /**
+     * A simple token provider for bearer authentication.
+     *
+     * Use this instead of `authProvider` when tokens are managed externally
+     * (e.g., upfront auth, gateway/proxy patterns, service accounts).
+     *
+     * If both `authProvider` and `tokenProvider` are set, `authProvider` takes precedence.
+     */
+    tokenProvider?: TokenProvider;
+
     /**
      * Customizes the initial SSE request to the server (the request that begins the stream).
      *
@@ -72,6 +83,7 @@ export class SSEClientTransport implements Transport {
     private _eventSourceInit?: EventSourceInit;
     private _requestInit?: RequestInit;
     private _authProvider?: OAuthClientProvider;
+    private _tokenProvider?: TokenProvider;
     private _fetch?: FetchLike;
     private _fetchWithInit: FetchLike;
     private _protocolVersion?: string;
@@ -87,6 +99,7 @@ export class SSEClientTransport implements Transport {
         this._eventSourceInit = opts?.eventSourceInit;
         this._requestInit = opts?.requestInit;
         this._authProvider = opts?.authProvider;
+        this._tokenProvider = opts?.tokenProvider;
         this._fetch = opts?.fetch;
         this._fetchWithInit = createFetchWithInit(opts?.fetch, opts?.requestInit);
     }
@@ -123,6 +136,11 @@ export class SSEClientTransport implements Transport {
             if (tokens) {
                 headers['Authorization'] = `Bearer ${tokens.access_token}`;
             }
+        } else if (this._tokenProvider) {
+            const token = await this._tokenProvider();
+            if (token) {
+                headers['Authorization'] = `Bearer ${token}`;
+            }
         }
         if (this._protocolVersion) {
             headers['mcp-protocol-version'] = this._protocolVersion;
@@ -161,9 +179,17 @@ export class SSEClientTransport implements Transport {
             this._abortController = new AbortController();
 
             this._eventSource.onerror = event => {
-                if (event.code === 401 && this._authProvider) {
-                    this._authThenStart().then(resolve, reject);
-                    return;
+                if (event.code === 401) {
+                    if (this._authProvider) {
+                        this._authThenStart().then(resolve, reject);
+                        return;
+                    }
+                    if (this._tokenProvider) {
+                        const error = new UnauthorizedError('Server returned 401 — token from tokenProvider was rejected');
+                        reject(error);
+                        this.onerror?.(error);
+                        return;
+                    }
                 }
 
                 const error = new SseError(event.code, event.message, event);
@@ -263,23 +289,28 @@ export class SSEClientTransport implements Transport {
             if (!response.ok) {
                 const text = await response.text?.().catch(() => null);
 
-                if (response.status === 401 && this._authProvider) {
-                    const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
-                    this._resourceMetadataUrl = resourceMetadataUrl;
-                    this._scope = scope;
+                if (response.status === 401) {
+                    if (this._authProvider) {
+                        const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
+                        this._resourceMetadataUrl = resourceMetadataUrl;
+                        this._scope = scope;
 
-                    const result = await auth(this._authProvider, {
-                        serverUrl: this._url,
-                        resourceMetadataUrl: this._resourceMetadataUrl,
-                        scope: this._scope,
-                        fetchFn: this._fetchWithInit
-                    });
-                    if (result !== 'AUTHORIZED') {
-                        throw new UnauthorizedError();
+                        const result = await auth(this._authProvider, {
+                            serverUrl: this._url,
+                            resourceMetadataUrl: this._resourceMetadataUrl,
+                            scope: this._scope,
+                            fetchFn: this._fetchWithInit
+                        });
+                        if (result !== 'AUTHORIZED') {
+                            throw new UnauthorizedError();
+                        }
+
+                        // Purposely _not_ awaited, so we don't call onerror twice
+                        return this.send(message);
+                    }
+                    if (this._tokenProvider) {
+                        throw new UnauthorizedError('Server returned 401 — token from tokenProvider was rejected');
                     }
-
-                    // Purposely _not_ awaited, so we don't call onerror twice
-                    return this.send(message);
                 }
 
                 throw new Error(`Error POSTing to endpoint (HTTP ${response.status}): ${text}`);