This is the documentation for the v2 beta — looking for the v1 documentation?
MCP TypeScript SDK

Appearance

MCP TypeScript SDK (V2) / @modelcontextprotocol/client / client/middleware

client/middleware ​

Type Aliases ​

LoggingOptions ​

LoggingOptions = object

Defined in: packages/client/src/client/middleware.ts:116

Configuration options for the logging middleware

Properties ​

includeRequestHeaders? ​

optional includeRequestHeaders?: boolean

Defined in: packages/client/src/client/middleware.ts:126

Whether to include request headers in logs

Default ​
ts
false
includeResponseHeaders? ​

optional includeResponseHeaders?: boolean

Defined in: packages/client/src/client/middleware.ts:132

Whether to include response headers in logs

Default ​
ts
false
logger? ​

optional logger?: RequestLogger

Defined in: packages/client/src/client/middleware.ts:120

Custom logger function, defaults to console logging

statusLevel? ​

optional statusLevel?: number

Defined in: packages/client/src/client/middleware.ts:139

Status level filter - only log requests with status >= this value Set to 0 to log all requests, 400 to log only errors

Default ​
ts
0

Middleware ​

Middleware = (next) => FetchLike

Defined in: packages/client/src/client/middleware.ts:10

Middleware function that wraps and enhances fetch functionality. Takes a fetch handler and returns an enhanced fetch handler.

Parameters ​

next ​

FetchLike

Returns ​

FetchLike

RequestLogger ​

RequestLogger = (input) => void

Defined in: packages/client/src/client/middleware.ts:102

Logger function type for HTTP requests

Parameters ​

input ​
duration ​

number

error? ​

Error

method ​

string

requestHeaders? ​

Headers

responseHeaders? ​

Headers

status ​

number

statusText ​

string

url ​

string | URL

Returns ​

void

Functions ​

applyMiddlewares() ​

applyMiddlewares(...middleware): Middleware

Defined in: packages/client/src/client/middleware.ts:249

Composes multiple fetch middleware functions into a single middleware pipeline. Middleware are applied in the order they appear, creating a chain of handlers.

Parameters ​

middleware ​

...Middleware[]

Array of fetch middleware to compose into a pipeline

Returns ​

Middleware

A single composed middleware function

Example ​

ts
// Create a middleware pipeline that handles both OAuth and logging
const enhancedFetch = applyMiddlewares(withOAuth(oauthProvider, 'https://api.example.com'), withLogging({ statusLevel: 400 }))(fetch);

// Use the enhanced fetch - it will handle auth and log errors
const response = await enhancedFetch('https://api.example.com/data');

createMiddleware() ​

createMiddleware(handler): Middleware

Defined in: packages/client/src/client/middleware.ts:317

Helper function to create custom fetch middleware with cleaner syntax. Provides the next handler and request details as separate parameters for easier access.

Parameters ​

handler ​

(next, input, init?) => Promise<Response>

Function that receives the next handler and request parameters

Returns ​

Middleware

A fetch middleware function

Example ​

ts
// Create custom authentication middleware
const customAuthMiddleware = createMiddleware(async (next, input, init) => {
    const headers = new Headers(init?.headers);
    headers.set('X-Custom-Auth', 'my-token');

    const response = await next(input, { ...init, headers });

    if (response.status === 401) {
        console.log('Authentication failed');
    }

    return response;
});

// Create conditional middleware
const conditionalMiddleware = createMiddleware(async (next, input, init) => {
    const url = typeof input === 'string' ? input : input.toString();

    // Only add headers for API routes
    if (url.includes('/api/')) {
        const headers = new Headers(init?.headers);
        headers.set('X-API-Version', 'v2');
        return next(input, { ...init, headers });
    }

    // Pass through for non-API routes
    return next(input, init);
});

// Create caching middleware
const cacheMiddleware = createMiddleware(async (next, input, init) => {
    const cacheKey = typeof input === 'string' ? input : input.toString();

    // Check cache first
    const cached = await getFromCache(cacheKey);
    if (cached) {
        return new Response(cached, { status: 200 });
    }

    // Make request and cache result
    const response = await next(input, init);
    if (response.ok) {
        await saveToCache(cacheKey, await response.clone().text());
    }

    return response;
});

withLogging() ​

withLogging(options?): Middleware

Defined in: packages/client/src/client/middleware.ts:158

Creates a fetch middleware that logs HTTP requests and responses.

When called without arguments withLogging(), it uses the default logger that:

  • Logs successful requests (2xx) to console.log
  • Logs error responses (4xx/5xx) and network errors to console.error
  • Logs all requests regardless of status (statusLevel: 0)
  • Does not include request or response headers in logs
  • Measures and displays request duration in milliseconds

Important: the default logger uses both console.log and console.error so it should not be used with stdio transports and applications.

Parameters ​

options? ​

LoggingOptions = {}

Logging configuration options

Returns ​

Middleware

A fetch middleware function

withOAuth() ​

withOAuth(provider, baseUrl?): Middleware

Defined in: packages/client/src/client/middleware.ts:39

Creates a fetch wrapper that handles OAuth authentication automatically.

This wrapper will:

  • Add Authorization headers with access tokens
  • Handle 401 responses by attempting re-authentication
  • Retry the original request after successful auth
  • Handle OAuth errors appropriately (OAuthErrorCode.InvalidClient, etc.)

The baseUrl parameter is optional and defaults to using the domain from the request URL. However, you should explicitly provide baseUrl when:

  • Making requests to multiple subdomains (e.g., api.example.com, cdn.example.com)
  • Using API paths that differ from OAuth discovery paths (e.g., requesting /api/v1/data but OAuth is at /)
  • The OAuth server is on a different domain than your API requests
  • You want to ensure consistent OAuth behavior regardless of request URLs

For MCP transports, set baseUrl to the same URL you pass to the transport constructor.

Note: This wrapper is designed for general-purpose fetch operations. MCP transports (SSE and StreamableHTTP) already have built-in OAuth handling and should not need this wrapper.

Parameters ​

provider ​

OAuthClientProvider

OAuth client provider for authentication

baseUrl? ​

string | URL

Base URL for OAuth server discovery (defaults to request URL domain)

Returns ​

Middleware

A fetch middleware function