Handle data-plane redirects explicitly in the client transports

StreamableHTTPClientTransport and SSEClientTransport issue their MCP
requests (POST sends, SSE stream GETs, session DELETE) with
redirect: 'manual' and apply RFC 9110 redirect semantics themselves:
GET redirects are followed for up to 3 hops, with the connection's
configured headers scoped to the endpoint's origin (a cross-origin hop
carries only Accept, MCP-Protocol-Version and Last-Event-ID);
POST/DELETE requests are never re-sent to a Location target and surface
the redirect as SdkHttpError with the new code
ClientHttpRedirectNotFollowed. A redirect response can no longer supply
the mcp-session-id the transport adopts. The new redirectPolicy
transport option ('manual' | 'follow', default 'manual') restores
delegation to the fetch implementation for deployments behind
redirecting infrastructure and for browser runtimes.

Author: felixweinberger

.changeset/transport-redirect-policy.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/core-internal': patch
+---
+
+Handle redirect (3xx) responses on the client transports' MCP requests explicitly instead of delegating them to the `fetch` implementation. `StreamableHTTPClientTransport` and `SSEClientTransport` now issue their data-plane requests (`POST` message sends, the `GET` that opens or resumes an SSE stream, the session-terminating `DELETE`) with `redirect: 'manual'` and apply RFC 9110 redirect semantics themselves: `GET` redirects are followed for up to 3 hops — a same-origin `Location` target is requested with the original headers, while a hop that leaves the endpoint's origin is requested with only the headers that describe the request itself (`Accept`, `MCP-Protocol-Version`, and — on `StreamableHTTPClientTransport` stream resumption — `Last-Event-ID`); headers configured for the connection (`requestInit` headers, the auth provider's `Authorization`, the server-issued `Mcp-Session-Id`) are not applied across origins. `POST` and `DELETE` requests are never re-sent to a `Location` target: a redirect answer to those surfaces as an `SdkHttpError` with the new code `SdkErrorCode.ClientHttpRedirectNotFollowed` (MCP endpoints that answer `POST` with a redirect are not followed — point the transport at the new endpoint instead), and a redirect response can no longer supply the `mcp-session-id` the transport adopts. The new transport option `redirectPolicy: 'manual' | 'follow'` (default `'manual'`) is the escape hatch: `'follow'` restores the previous behavior — no `redirect` field is set, so `requestInit.redirect` or the platform default applies — for deployments behind redirecting infrastructure that requires the configured headers on the redirect target, and for browser runtimes: there `redirect: 'manual'` yields an opaque redirect (Fetch `opaqueredirect`: status 0, no readable `Location` header) whose target the transport cannot observe, so under the default `'manual'` policy any redirect answer — initial or on a followed hop — fails with `ClientHttpRedirectNotFollowed` and a message naming the remedies (set `redirectPolicy: 'follow'`, or serve the MCP endpoint without redirects) instead of an unexplained status-0 failure. See the "HTTP & headers" section of `docs/migration/upgrade-to-v2.md`.

docs/migration/upgrade-to-v2.md

@@ -811,6 +811,56 @@ value to the spec-required `application/json, text/event-stream` (v1 let it repl
 them). The required media types are always present; additional types are kept for
 proxy/gateway routing.
 
+#### Redirect (3xx) responses on MCP requests
+
+`StreamableHTTPClientTransport` and `SSEClientTransport` no longer delegate redirect
+handling on their MCP requests to the `fetch` implementation (v1 let the platform
+follow up to 20 hops with every header riding along). Data-plane requests — `POST`
+message sends, the `GET` that opens or resumes an SSE stream, the session-terminating
+`DELETE` — now go out with `redirect: 'manual'` and the transport applies RFC 9110
+redirect semantics itself:
+
+- **`GET`** redirects are followed, bounded at **3 hops**. A same-origin `Location`
+  target is requested with the original headers. A hop that leaves the endpoint's
+  origin is requested with only the headers that describe the request itself
+  (`Accept`, `MCP-Protocol-Version`, and — on `StreamableHTTPClientTransport`
+  stream resumption — `Last-Event-ID`: what the target needs to negotiate the
+  media type, parse the request, and resume the stream). Headers
+  configured for the _connection_ — `requestInit` headers, the auth provider's
+  `Authorization`, the server-issued `Mcp-Session-Id` — are scoped to the configured
+  origin and are not applied across origins. Once a chain has left the origin,
+  the reduced header set applies to every remaining hop, including one that
+  returns to the original origin.
+- **`POST` / `DELETE`** requests are **never re-sent** to a `Location` target
+  (RFC 9110 leaves redirecting a request with a body to the sender's discretion). A
+  redirect answer surfaces as `SdkHttpError` with the new code
+  `SdkErrorCode.ClientHttpRedirectNotFollowed`; an MCP endpoint that answers `POST`
+  with a redirect is a configuration to fix by pointing the transport at the new
+  endpoint URL. A redirect response also can no longer supply the `mcp-session-id`
+  value the transport adopts — session ids are only read off responses the
+  configured endpoint answered directly.
+
+The escape hatch is the new `redirectPolicy` transport option (both transports):
+
+```ts
+const transport = new StreamableHTTPClientTransport(url, {
+    redirectPolicy: 'follow' // default: 'manual'
+});
+```
+
+`'follow'` restores the v1 request shape exactly — no `redirect` field is set, so
+`requestInit.redirect` or the platform default (`'follow'`) applies and every
+request's headers ride along to wherever the chain ends. Set it for deployments
+behind redirecting infrastructure that requires the configured headers on the
+redirect target, and for browser runtimes: a browser `fetch` answers
+`redirect: 'manual'` with an opaque redirect (Fetch `opaqueredirect`: status 0, no
+readable `Location` header), so the transport cannot observe the redirect target to
+apply the rules above. Under the default `'manual'` policy any redirect answer —
+initial or on a followed hop, any method — therefore fails there with
+`ClientHttpRedirectNotFollowed` (`status` is the literal `0`), its message naming the
+two ways out: set `redirectPolicy: 'follow'`, or serve the MCP endpoint without
+redirects.
+
 `hostHeaderValidation()` and `localhostHostValidation()` moved to
 `@modelcontextprotocol/express`. The `(allowedHostnames: string[])` signature is the
 same as every released v1.x — only the import path changes. Framework-agnostic helpers
@@ -848,7 +898,7 @@ hierarchy also exposes the same check as an explicit static guard
 TypeScript — use whichever style your codebase prefers; both read the same brand.
 Fine print (applies equally to `instanceof` and `isInstance`):
 
-- **Version skew** — matching needs *both* copies at a brand-aware release; against an
+- **Version skew** — matching needs _both_ copies at a brand-aware release; against an
   older copy, behavior degrades to plain prototype `instanceof` (false across bundles).
   During mixed-version rollouts, recognize errors without class identity: match
   `error.name` plus the class's discriminant field (`code`, `status`), or reconstruct

packages/client/src/client/sse.ts

@@ -23,6 +23,8 @@ import {
 } from './auth';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced in JSDoc {@linkcode}
 import type { IssuerMismatchError } from './authErrors';
+import type { RedirectPolicy } from './transportRedirect';
+import { fetchWithRedirectPolicy } from './transportRedirect';
 
 export class SseError extends Error {
     static {
@@ -114,6 +116,14 @@ export type SSEClientTransportOptions = {
      * Custom fetch implementation used for all network requests.
      */
     fetch?: FetchLike;
+
+    /**
+     * How the transport reacts to redirect (3xx) responses on its MCP requests.
+     * See {@linkcode RedirectPolicy}.
+     *
+     * @default 'manual'
+     */
+    redirectPolicy?: RedirectPolicy;
 };
 
 /**
@@ -136,6 +146,7 @@ export class SSEClientTransport implements Transport {
     private _fetch?: FetchLike;
     /** Fetch for OAuth requests — deliberately merges `oauthRequestInit`, never `requestInit`. */
     private _authFetch: FetchLike;
+    private _redirectPolicy: RedirectPolicy;
     private _protocolVersion?: string;
 
     onclose?: () => void;
@@ -158,6 +169,7 @@ export class SSEClientTransport implements Transport {
             this._authProvider = opts?.authProvider;
         }
         this._fetch = opts?.fetch;
+        this._redirectPolicy = opts?.redirectPolicy ?? 'manual';
         this._authFetch = createFetchWithInit(opts?.fetch, opts?.oauthRequestInit);
     }
 
@@ -189,10 +201,32 @@ export class SSEClientTransport implements Transport {
                 fetch: async (url, init) => {
                     const headers = await this._commonHeaders();
                     headers.set('Accept', 'text/event-stream');
-                    const response = await fetchImpl(url, {
-                        ...init,
-                        headers
-                    });
+                    const crossOriginHeaders = new Headers({ accept: 'text/event-stream' });
+                    if (this._protocolVersion) {
+                        crossOriginHeaders.set('mcp-protocol-version', this._protocolVersion);
+                    }
+                    let response: Response;
+                    try {
+                        response = await fetchWithRedirectPolicy({
+                            fetchFn: fetchImpl,
+                            url,
+                            method: 'GET',
+                            headers,
+                            requestInit: init as RequestInit,
+                            signal: (init as RequestInit | undefined)?.signal ?? undefined,
+                            redirectPolicy: this._redirectPolicy,
+                            crossOriginHeaders
+                        });
+                    } catch (error) {
+                        if (error instanceof SdkHttpError && error.code === SdkErrorCode.ClientHttpRedirectNotFollowed) {
+                            // Terminal, not transient: close so the EventSource does not
+                            // schedule reconnects against the same redirecting endpoint.
+                            reject(error);
+                            this.onerror?.(error);
+                            void this.close();
+                        }
+                        throw error;
+                    }
 
                     if (response.status === 401) {
                         this._last401Response = response;
@@ -349,15 +383,16 @@ export class SSEClientTransport implements Transport {
         try {
             const headers = await this._commonHeaders();
             headers.set('content-type', 'application/json');
-            const init = {
-                ...this._requestInit,
+            const response = await fetchWithRedirectPolicy({
+                fetchFn: this._fetch ?? fetch,
+                url: this._endpoint,
                 method: 'POST',
                 headers,
+                requestInit: this._requestInit,
                 body: JSON.stringify(message),
-                signal: this._abortController?.signal
-            };
-
-            const response = await (this._fetch ?? fetch)(this._endpoint, init);
+                signal: this._abortController?.signal,
+                redirectPolicy: this._redirectPolicy
+            });
             if (!response.ok) {
                 if (response.status === 401 && this._authProvider) {
                     if (response.headers.has('www-authenticate')) {

packages/client/src/client/streamableHttp.ts

@@ -33,6 +33,8 @@ import {
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced via {@linkcode} in finishAuth JSDoc
 import type { IssuerMismatchError } from './authErrors';
 import { InsufficientScopeError } from './authErrors';
+import type { RedirectPolicy } from './transportRedirect';
+import { fetchWithRedirectPolicy } from './transportRedirect';
 
 /** Default cap on step-up re-authorization retries within a single send/stream-open. */
 const DEFAULT_MAX_STEP_UP_RETRIES = 1;
@@ -188,6 +190,14 @@ export type StreamableHTTPClientTransportOptions = {
      */
     fetch?: FetchLike;
 
+    /**
+     * How the transport reacts to redirect (3xx) responses on its MCP requests.
+     * See {@linkcode RedirectPolicy}.
+     *
+     * @default 'manual'
+     */
+    redirectPolicy?: RedirectPolicy;
+
     /**
      * Options to configure the reconnection behavior.
      */
@@ -317,6 +327,7 @@ export class StreamableHTTPClientTransport implements Transport {
     private _oauthProvider?: OAuthClientProvider;
     private _skipIssuerMetadataValidation?: boolean;
     private _fetch?: FetchLike;
+    private _redirectPolicy: RedirectPolicy;
     /** Fetch for OAuth requests — deliberately merges `oauthRequestInit`, never `requestInit`. */
     private _authFetch: FetchLike;
     private _sessionId?: string;
@@ -355,6 +366,7 @@ export class StreamableHTTPClientTransport implements Transport {
             this._authProvider = opts?.authProvider;
         }
         this._fetch = opts?.fetch;
+        this._redirectPolicy = opts?.redirectPolicy ?? 'manual';
         this._authFetch = createFetchWithInit(opts?.fetch, opts?.oauthRequestInit);
         this._sessionId = opts?.sessionId;
         this._protocolVersion = opts?.protocolVersion;
@@ -446,6 +458,22 @@ export class StreamableHTTPClientTransport implements Transport {
         });
     }
 
+    /**
+     * Headers a followed `GET` redirect carries to another origin —
+     * connection-scoped headers (`Authorization`, `Mcp-Session-Id`,
+     * `requestInit`) are deliberately omitted.
+     */
+    private _crossOriginGetHeaders(resumptionToken?: string): Headers {
+        const headers = new Headers({ accept: 'text/event-stream' });
+        if (this._protocolVersion) {
+            headers.set('mcp-protocol-version', this._protocolVersion);
+        }
+        if (resumptionToken) {
+            headers.set('last-event-id', resumptionToken);
+        }
+        return headers;
+    }
+
     /**
      * Body-derived per-request headers: when an outgoing request carries a
      * protocol-version claim in its `_meta` envelope (the version negotiation
@@ -529,11 +557,15 @@ export class StreamableHTTPClientTransport implements Transport {
                 requestSignal !== undefined && transportSignal !== undefined
                     ? anySignal(transportSignal, requestSignal)
                     : (requestSignal ?? transportSignal);
-            const response = await (this._fetch ?? fetch)(this._url, {
-                ...this._requestInit,
+            const response = await fetchWithRedirectPolicy({
+                fetchFn: this._fetch ?? fetch,
+                url: this._url,
                 method: 'GET',
                 headers,
-                signal
+                requestInit: this._requestInit,
+                signal,
+                redirectPolicy: this._redirectPolicy,
+                crossOriginHeaders: this._crossOriginGetHeaders(resumptionToken)
             });
 
             if (!response.ok) {
@@ -968,15 +1000,16 @@ export class StreamableHTTPClientTransport implements Transport {
                 options?.requestSignal !== undefined && transportSignal !== undefined
                     ? anySignal(transportSignal, options.requestSignal)
                     : (options?.requestSignal ?? transportSignal);
-            const init = {
-                ...this._requestInit,
+            const response = await fetchWithRedirectPolicy({
+                fetchFn: this._fetch ?? fetch,
+                url: this._url,
                 method: 'POST',
                 headers,
+                requestInit: this._requestInit,
                 body: JSON.stringify(message),
-                signal
-            };
-
-            const response = await (this._fetch ?? fetch)(this._url, init);
+                signal,
+                redirectPolicy: this._redirectPolicy
+            });
 
             // Handle session ID received during initialization
             const sessionId = response.headers.get('mcp-session-id');
@@ -1161,14 +1194,15 @@ export class StreamableHTTPClientTransport implements Transport {
         try {
             const headers = await this._commonHeaders();
 
-            const init = {
-                ...this._requestInit,
+            const response = await fetchWithRedirectPolicy({
+                fetchFn: this._fetch ?? fetch,
+                url: this._url,
                 method: 'DELETE',
                 headers,
-                signal: this._abortController?.signal
-            };
-
-            const response = await (this._fetch ?? fetch)(this._url, init);
+                requestInit: this._requestInit,
+                signal: this._abortController?.signal,
+                redirectPolicy: this._redirectPolicy
+            });
             await response.text?.().catch(() => {});
 
             // We specifically handle 405 as a valid response according to the spec,