fix(client): scope transport headers to MCP requests and handle redirects explicitly

.changeset/token-registration-redirects-terminal.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Token and client registration requests no longer follow HTTP redirects — including the cross-app access token exchanges. Token responses are terminal (RFC 6749 §5), so a 3xx answer from a token or registration endpoint now rejects with an error instead of being re-sent to the redirect target.

.changeset/transport-headers-oauth-requests.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Transport `requestInit` headers now apply only to MCP requests, not to the OAuth requests issued by the transport's authorization flow (protected-resource metadata, authorization-server metadata, token, and client registration requests) — those may target a different origin than the MCP server, so connection-level headers do not carry over. A new `oauthRequestInit` transport option configures those requests explicitly.

.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
@@ -1112,6 +1162,22 @@ OAuth `onUnauthorized` behavior, for composing your own adapter).
 - **Metadata discovery falls through on 502.** `discoverAuthorizationServerMetadata()`
   treats `502 Bad Gateway` like 4xx — fall through to the next candidate URL instead of
   throwing (fixes path-aware discovery behind reverse proxies). Other 5xx still throw.
+- **Transport `requestInit` headers stay off OAuth requests.** Headers configured via
+  the `requestInit` option on `StreamableHTTPClientTransport` / `SSEClientTransport`
+  apply only to MCP requests; the OAuth requests the transport's authorization flow
+  issues (protected-resource metadata, authorization-server metadata, token, and client
+  registration requests) are sent without them — those may target a different origin
+  than the MCP server, so connection-level headers do not carry over. A deployment that
+  needs extra headers on those requests (e.g. gateway headers on well-known endpoints)
+  sets the new `oauthRequestInit` transport option.
+- **Token and registration endpoint redirects are not followed.** The token-exchange
+  and client-registration POSTs (`exchangeAuthorization()` / `refreshAuthorization()` /
+  `fetchToken()` / `registerClient()`, transitively `auth()`, and the cross-app access
+  token exchanges `requestJwtAuthorizationGrant()` / `exchangeJwtAuthGrant()`) are issued with
+  `redirect: 'manual'`; a 3xx answer rejects with an error instead of re-sending the
+  request to the redirect target. Token responses are terminal (RFC 6749 §5) — an
+  authorization server that redirects these requests must be addressed at its final
+  endpoint URL (via its metadata document).
 - **Scoped credential invalidation on `invalid_client` / `unauthorized_client`.** The
   `auth()` retry for these errors now issues two scoped calls —
   `invalidateCredentials('client')` then `invalidateCredentials('tokens')` — instead of

packages/client/src/client/auth.ts

@@ -2046,6 +2046,18 @@ export function prepareAuthorizationCodeRequest(
     });
 }
 
+/**
+ * Token and registration responses are terminal (RFC 6749 §5, RFC 7591 §3.2):
+ * a redirect — including one the runtime filters to `opaqueredirect` — is an error.
+ */
+export function assertNotRedirected(response: Response, endpoint: 'Token' | 'Registration'): void {
+    if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) {
+        throw new Error(
+            `${endpoint} endpoint responded with a redirect (HTTP ${response.status || 'filtered by the runtime'}); ${endpoint.toLowerCase()} responses are terminal`
+        );
+    }
+}
+
 /**
  * Internal helper to execute a token request with the given parameters.
  * Used by {@linkcode exchangeAuthorization}, {@linkcode refreshAuthorization}, and {@linkcode fetchToken}.
@@ -2090,8 +2102,10 @@ export async function executeTokenRequest(
     const response = await (fetchFn ?? fetch)(tokenUrl, {
         method: 'POST',
         headers,
-        body: tokenRequestParams
+        body: tokenRequestParams,
+        redirect: 'manual'
     });
+    assertNotRedirected(response, 'Token');
 
     if (!response.ok) {
         throw await parseErrorResponse(response);
@@ -2365,8 +2379,10 @@ export async function registerClient(
         headers: {
             'Content-Type': 'application/json'
         },
-        body: JSON.stringify(submittedMetadata)
+        body: JSON.stringify(submittedMetadata),
+        redirect: 'manual'
     });
+    assertNotRedirected(response, 'Registration');
 
     if (!response.ok) {
         throw new RegistrationRejectedError({ status: response.status, body: await response.text(), submittedMetadata });

packages/client/src/client/crossAppAccess.ts

@@ -12,7 +12,7 @@ import type { FetchLike } from '@modelcontextprotocol/core-internal';
 import { IdJagTokenExchangeResponseSchema, OAuthErrorResponseSchema, OAuthTokensSchema } from '@modelcontextprotocol/core-internal';
 
 import type { ClientAuthMethod } from './auth';
-import { applyClientAuthentication, assertSecureTokenEndpoint, discoverAuthorizationServerMetadata } from './auth';
+import { applyClientAuthentication, assertNotRedirected, assertSecureTokenEndpoint, discoverAuthorizationServerMetadata } from './auth';
 
 /**
  * Options for requesting a JWT Authorization Grant via RFC 8693 Token Exchange.
@@ -152,8 +152,10 @@ export async function requestJwtAuthorizationGrant(options: RequestJwtAuthGrantO
         headers: {
             'Content-Type': 'application/x-www-form-urlencoded'
         },
-        body: params.toString()
+        body: params.toString(),
+        redirect: 'manual'
     });
+    assertNotRedirected(response, 'Token');
 
     if (!response.ok) {
         const errorBody = await response.json().catch(() => ({}));
@@ -279,8 +281,10 @@ export async function exchangeJwtAuthGrant(options: {
     const response = await fetchFn(tokenUrl, {
         method: 'POST',
         headers,
-        body: params.toString()
+        body: params.toString(),
+        redirect: 'manual'
     });
+    assertNotRedirected(response, 'Token');
 
     if (!response.ok) {
         const errorBody = await response.json().catch(() => ({}));