fix(client): treat HTTP 401/403 on the negotiation probe as auth failures, not legacy evidence

A 401 (without an authProvider) or 403 rejection of the connect-time
server/discover probe fell into the classifier's conservative legacy
fallback: auto mode sent a doomed legacy initialize, and pin mode
reported "the server did not offer pinned protocol version ..." for a
server that was never asked. Auth status is not era evidence.

classifyHttpError now has an explicit 401/403 row ahead of the JSON-RPC
body parse: a typed SdkHttpError (EraNegotiationFailed) carrying the
HTTP status, reason phrase, and response text — never a legacy verdict.
The probe's send-error normalization also propagates the transport auth
flow's own typed failures unchanged (UnauthorizedError for finishAuth,
OAuthError such as invalid_grant from a failed token refresh,
InsufficientScopeError and the OAuthClientFlowError family, the
401-after-re-authentication diagnostic) instead of flattening them into
the generic HTTP row.

Untyped errors escaping the SDK's own OAuth flow (e.g. a fetch
TypeError from the dynamic-client-registration POST) are wrapped as
typed SdkErrors (ClientHttpAuthentication / ClientHttpForbidden, the
original as cause), so an auth-flow crash can no longer fall into the
probe's browser CORS heuristic and read as legacy-era evidence.

An e2e requirement pins the common production shape end to end: an
OAuth-protected legacy server under mode 'auto' — probe 401'd, auth
challenge propagated, finishAuth, reconnect re-probes with the token,
the legacy rejection supplies the era evidence, initialize and
tools/call succeed.

Fixes #2561

Author: felixweinberger

.changeset/probe-auth-status-not-era-evidence.md

@@ -0,0 +1,24 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+The version-negotiation probe no longer misclassifies auth-protected servers
+(HTTP 401/403) as legacy. A 401 or 403 rejection of the `server/discover`
+probe now surfaces as a typed authorization failure — an `SdkHttpError` with
+code `EraNegotiationFailed` carrying the HTTP status, reason phrase, and
+response text (a 403 `insufficient_scope` challenge instead surfaces the
+flow's typed `InsufficientScopeError`) — instead of triggering the legacy
+`initialize` fallback (which put a doomed `initialize` on the wire) or,
+under `pin` mode, the false "server did not offer pinned protocol version"
+diagnostic. With an `authProvider` the transport's auth flow still runs
+first and its outcome now always propagates unchanged: `UnauthorizedError`
+for `finishAuth()` as before, and the flow's own typed failures
+(`OAuthError` such as `invalid_grant` from a failed token refresh,
+`InsufficientScopeError`, the 401-after-re-authentication diagnostic)
+instead of a legacy verdict or a generic negotiation wrap. Untyped errors
+escaping the SDK's own OAuth flow (e.g. a fetch `TypeError` from the
+dynamic-client-registration POST) are now wrapped as `SdkError` with code
+`ClientHttpAuthentication` (401 flow) or `ClientHttpForbidden` (step-up flow)
+and the original error as `cause`, so an auth-flow crash is never misread as
+probe-level network evidence — previously, in a browser, such a `TypeError`
+fell into the probe's CORS heuristic and produced a legacy-era verdict.

docs/clients/oauth.md

@@ -2,6 +2,7 @@
 shape: how-to
 description: 'Sign an end user in from a client you build with the OAuth authorization-code flow.'
 ---
+
 # Authenticate a user with OAuth
 
 Protecting a server you run → [Require authorization](../serving/authorization.md). Signing a user in from a client → this page. No user present → [Authenticate without a user](./machine-auth.md).
@@ -29,7 +30,7 @@ try {
 When the server requires authorization and the provider has no token, the SDK runs discovery against the server, registers (or looks up) your OAuth client, calls the provider's `redirectToAuthorization(url)`, and `connect()` throws `UnauthorizedError`. The end user finishes signing in out of band; your callback endpoint picks the flow back up below.
 
 ::: info
-With protocol-version negotiation in play, the connect-time 401 can also surface as an `SdkError` carrying the `UnauthorizedError` at `error.data.cause` — see [Protocol versions](../protocol-versions.md).
+With protocol-version negotiation in play (`versionNegotiation: { mode: 'auto' }` or a pin), the connect-time `UnauthorizedError` propagates unchanged from `connect()` — the same `instanceof` check works in every mode (older releases wrapped it as an `SdkError` with the error at `error.data.cause`). See [Protocol versions](../protocol-versions.md).
 :::
 
 ## Implement OAuthClientProvider

docs/migration/support-2026-07-28.md

@@ -76,7 +76,11 @@ infrastructure problems. Anything the probe does not positively recognize as mod
 falls back to the legacy era — provided the supported-versions list still contains a
 2025-era revision; with a modern-only list `connect()` rejects with
 `SdkError(EraNegotiationFailed)` instead. A network outage rejects with a typed connect
-error. Probe timeouts are **transport-aware**: on **stdio** a server that does not
+error. Auth statuses are another exception: an HTTP `401` or `403` rejecting the probe
+is never era evidence — `connect()` rejects with a typed authorization failure (an
+`SdkHttpError(EraNegotiationFailed)` naming the status, or the transport auth flow's
+own typed error propagated unchanged) instead of falling back — see
+[Protocol versions](../protocol-versions.md). Probe timeouts are **transport-aware**: on **stdio** a server that does not
 answer within `timeoutMs` is treated as legacy and the client falls back to `initialize`
 (some legacy servers never respond to unknown pre-`initialize`
 requests at all); on **HTTP** a probe timeout rejects with `SdkError(RequestTimeout)` —

docs/migration/upgrade-to-v2.md

@@ -1151,11 +1151,11 @@ try {
 }
 ```
 
-One qualification: this direct `instanceof` check applies under the default `'legacy'`
-version negotiation. Under the probing modes (`versionNegotiation: { mode: 'auto' }`,
-with or without a pin) the connect-time 401 currently surfaces wrapped as
-`SdkError(SdkErrorCode.EraNegotiationFailed)` with the `UnauthorizedError` at
-`error.data.cause` — unwrap before the check, as shown in the
+This direct `instanceof` check works in every version-negotiation mode: under the
+probing modes (`versionNegotiation: { mode: 'auto' }`, with or without a pin) the
+connect-time `UnauthorizedError` also propagates unchanged from `connect()`. Older
+releases wrapped it as `SdkError(SdkErrorCode.EraNegotiationFailed)` with the error at
+`error.data.cause` — that unwrap is no longer needed. See the
 [client OAuth guide](../clients/oauth.md).
 
 #### `auth()` options are now `AuthOptions`

docs/protocol-versions.md

@@ -101,6 +101,8 @@ const cli = new Client(
 
 A probe timeout is transport-aware. On stdio a silent server is a legacy server, so `connect()` falls back to `initialize`; on HTTP silence is an outage, so `connect()` rejects with `SdkError(RequestTimeout)` instead of misreporting a dead server as legacy. One browser exception: an opaque CORS `TypeError` during the probe falls back to the legacy era, because deployed 2025 servers commonly have allow-lists that predate the 2026 headers.
 
+Auth statuses are not era evidence either. An HTTP `401` or `403` rejecting the probe surfaces as a typed authorization failure, never the legacy fallback. With no `authProvider`, `connect()` rejects with an `SdkHttpError(EraNegotiationFailed)` naming the status — except a `403` whose `WWW-Authenticate` challenge carries `error="insufficient_scope"`, where the transport's step-up handling (not gated on a provider) rejects with the flow's typed `InsufficientScopeError` instead. With a provider, the auth flow runs first and its outcome propagates unchanged — `UnauthorizedError` for `finishAuth()`, or the flow's own typed failure (an `OAuthError` such as `invalid_grant` from a failed token refresh, an `InsufficientScopeError`, the 401-after-re-authentication diagnostic). Auth settles first, era second: a `401` never decides the era — the auth wall answers before the MCP layer ever sees `server/discover` — and the post-auth re-probe supplies the real era evidence.
+
 On the SDK's own stdio transport (exactly `StdioClientTransport` — subclasses, like custom stdio-shaped transports, probe in place) the probe runs on a short-lived **sibling process** spawned from the same parameters — some stdio servers exit on any pre-`initialize` request (servers built on the official Rust SDK, rmcp, behave this way), so the probe must not spend the caller's one child process. The sibling is invisible infrastructure: its stderr is discarded and it is reaped once the era is known; the caller's transport spawns exactly once, afterwards, and its wire never carries `server/discover`. A child that exits on the probe is simply a legacy server (its exit must close the child's stdio pipes to register — an exit hidden behind a helper process holding them open falls to the probe-timeout path). Closing the caller's transport during the probe aborts `connect()` with a typed `SdkError(EraNegotiationFailed)` and the session child is never spawned. On HTTP — and on custom stdio-shaped transports, which probe in place — a mid-probe connection close rejects with the same typed error as any probe transport failure.
 
 The client's `supportedProtocolVersions` option shapes the probe: its 2026+ entries are the versions the probe offers, and the legacy fallback stays available only while the list keeps a pre-2026 entry. A list with no pre-2026 entry removes the fallback — against a 2025-only server, `connect()` rejects with `SdkError(EraNegotiationFailed)`.

examples/cli-client/host/host.ts

@@ -17,15 +17,13 @@ import {
     Client,
     LOG_LEVEL_META_KEY,
     ProtocolError,
-    SdkError,
     StreamableHTTPClientTransport,
     SUPPORTED_PROTOCOL_VERSIONS,
     UnauthorizedError
 } from '@modelcontextprotocol/client';
 import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 
 import type { ChatMessage, ContentPart, GenerateResult, LLMProvider, ToolCall, ToolDefinition } from '../providers/provider';
-import { isRecord } from '../providers/provider';
 import { completeAuthorizationWithBrowser, createOAuthProvider, findCallbackPort, isSafeBrowserUrl } from './auth';
 import type { CliClientConfig, ServerConfig } from './config';
 import { isHttpServer } from './config';
@@ -100,16 +98,6 @@ export function resolveVersionOptions(legacy: boolean, protocolVersion?: string)
     return { versionNegotiation: { mode: { pin: protocolVersion } } };
 }
 
-function unwrapUnauthorized(error: unknown): UnauthorizedError | undefined {
-    if (error instanceof UnauthorizedError) return error;
-    // Under versionNegotiation 'auto', a connect-time 401 surfaces as
-    // SdkError(EraNegotiationFailed) with the UnauthorizedError in error.data.cause.
-    if (error instanceof SdkError && isRecord(error.data) && error.data.cause instanceof UnauthorizedError) {
-        return error.data.cause;
-    }
-    return undefined;
-}
-
 function samplingContentToParts(content: CreateMessageRequest['params']['messages'][number]['content']): ContentPart[] {
     const blocks = Array.isArray(content) ? content : [content];
     const parts: ContentPart[] = [];
@@ -488,7 +476,9 @@ export class McpHost {
                 try {
                     await client.connect(httpTransport);
                 } catch (error) {
-                    if (!unwrapUnauthorized(error)) throw error;
+                    // A connect-time 401 propagates UnauthorizedError unchanged
+                    // in every negotiation mode, including the probing ones.
+                    if (!(error instanceof UnauthorizedError)) throw error;
                     const finishTransport = httpTransport;
                     const authorized = await completeAuthorizationWithBrowser({
                         serverName: name,

packages/client/src/client/auth.ts

@@ -25,11 +25,19 @@ import {
     OAuthTokensSchema,
     OpenIdProviderDiscoveryMetadataSchema,
     resourceUrlFromServerUrl,
+    SdkError,
+    SdkErrorCode,
     stampErrorBrands
 } from '@modelcontextprotocol/core-internal';
 import pkceChallenge from 'pkce-challenge';
 
-import { AuthorizationServerMismatchError, InsecureTokenEndpointError, IssuerMismatchError, RegistrationRejectedError } from './authErrors';
+import {
+    AuthorizationServerMismatchError,
+    InsecureTokenEndpointError,
+    IssuerMismatchError,
+    OAuthClientFlowError,
+    RegistrationRejectedError
+} from './authErrors';
 
 // Re-exported for back-compat — the canonical home is ./authErrors.js.
 export { AuthorizationServerMismatchError, InsecureTokenEndpointError, IssuerMismatchError, RegistrationRejectedError } from './authErrors';
@@ -169,6 +177,30 @@ export function isOAuthClientProvider(provider: AuthProvider | OAuthClientProvid
     return typeof p.tokens === 'function' && typeof p.clientInformation === 'function';
 }
 
+/**
+ * Keep auth-flow escapes recognizable as auth-flow failures: typed auth errors
+ * rethrow unchanged, while anything untyped thrown from inside {@linkcode auth}
+ * (e.g. a fetch `TypeError` from the dynamic-client-registration POST) is
+ * wrapped as an {@linkcode SdkError} with `code` and the original error as
+ * `data.cause`. Downstream classifiers — the version-negotiation probe's
+ * network-error row in particular, whose browser heuristic reads an opaque
+ * `TypeError` as legacy-era evidence — must never mistake an auth-flow crash
+ * for a transport-level network failure.
+ */
+export function rethrowTypedAuthFlowError(error: unknown, code: SdkErrorCode): never {
+    if (
+        error instanceof UnauthorizedError ||
+        error instanceof OAuthError ||
+        error instanceof OAuthClientFlowError ||
+        error instanceof SdkError
+    ) {
+        throw error;
+    }
+    throw new SdkError(code, `OAuth authorization flow failed: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error
+    });
+}
+
 /**
  * Standard `onUnauthorized` behavior for OAuth providers: extracts
  * `WWW-Authenticate` parameters from the 401 response and runs {@linkcode auth}.
@@ -180,13 +212,18 @@ export async function handleOAuthUnauthorized(
     extraAuthOptions?: Pick<AuthOptions, 'skipIssuerMetadataValidation'>
 ): Promise<void> {
     const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(ctx.response);
-    const result = await auth(provider, {
-        serverUrl: ctx.serverUrl,
-        resourceMetadataUrl,
-        scope,
-        fetchFn: ctx.fetchFn,
-        ...extraAuthOptions
-    });
+    let result: AuthResult;
+    try {
+        result = await auth(provider, {
+            serverUrl: ctx.serverUrl,
+            resourceMetadataUrl,
+            scope,
+            fetchFn: ctx.fetchFn,
+            ...extraAuthOptions
+        });
+    } catch (error) {
+        rethrowTypedAuthFlowError(error, SdkErrorCode.ClientHttpAuthentication);
+    }
     if (result !== 'AUTHORIZED') {
         throw new UnauthorizedError();
     }

packages/client/src/client/probeClassifier.ts

@@ -7,8 +7,9 @@
  * sibling), or a typed connect error.
  *
  * The classifier is deliberately conservative: anything it does not positively
- * recognize as modern resolves to the legacy fallback, and a network outage is a
- * typed connect error, never an era verdict. The verdicts apply to the
+ * recognize as modern resolves to the legacy fallback, and a network outage or
+ * an auth-status rejection (HTTP 401/403) is a typed connect error, never an
+ * era verdict. The verdicts apply to the
  * negotiation phase only — an established modern connection is never silently
  * demoted to `initialize` by a later failure.
  */
@@ -19,6 +20,7 @@ import {
     modernProtocolVersions,
     SdkError,
     SdkErrorCode,
+    SdkHttpError,
     UnsupportedProtocolVersionError
 } from '@modelcontextprotocol/core-internal';
 
@@ -46,10 +48,10 @@ export type ProbeOutcome =
     | { kind: 'result'; result: unknown }
     /** Answered with a JSON-RPC error (any HTTP status, including 200-bodied errors and stdio in-band errors). */
     | { kind: 'rpc-error'; code: number; message: string; data?: unknown }
-    /** The HTTP layer rejected the probe POST (non-2xx); `body` is the raw response text, when available. */
-    | { kind: 'http-error'; status: number; body?: string }
+    /** The HTTP layer rejected the probe POST (non-2xx); `body` is the raw response text and `statusText` the HTTP reason phrase, when available. */
+    | { kind: 'http-error'; status: number; body?: string; statusText?: string }
     | { kind: 'network-error'; error: unknown }
-    /** The transport's auth flow challenged during the probe send (`UnauthorizedError`). */
+    /** The transport's auth flow challenged or failed during the probe send (`UnauthorizedError`, an `OAuthClientFlowError`, or the transport's own re-auth/step-up diagnostics) — `error` propagates unchanged. */
     | { kind: 'auth-required'; error: Error }
     /** The transport reported close while the probe awaited its reply. */
     | { kind: 'closed' }
@@ -241,7 +243,24 @@ function classifyRpcError(outcome: { code: number; message: string; data?: unkno
     return { kind: 'legacy' };
 }
 
-function classifyHttpError(outcome: { status: number; body?: string }, context: ProbeClassifierContext): ProbeVerdict {
+function classifyHttpError(outcome: { status: number; body?: string; statusText?: string }, context: ProbeClassifierContext): ProbeVerdict {
+    // Auth statuses are never era evidence, and a 401/403 body is the auth
+    // layer's, not the server/discover handler's — this row ranks above the
+    // JSON-RPC body parse. Parallel to the auth-required row: a typed failure
+    // naming the status (response text on `data.text`), never a legacy
+    // fallback. This matches the non-probing legacy-mode client, which
+    // surfaces the same server as an `SdkHttpError` carrying this status.
+    if (outcome.status === 401 || outcome.status === 403) {
+        const detail = outcome.status === 401 ? 'the server requires authorization (HTTP 401)' : 'the server denied access (HTTP 403)';
+        return {
+            kind: 'error',
+            error: new SdkHttpError(SdkErrorCode.EraNegotiationFailed, `Version negotiation failed: ${detail}`, {
+                status: outcome.status,
+                statusText: outcome.statusText,
+                text: outcome.body
+            })
+        };
+    }
     // HTTP-rejected probes carry their JSON-RPC error in the response body — classify it like an in-band error.
     const rpcError = parseJsonRpcErrorBody(outcome.body);
     if (rpcError !== undefined) {

packages/client/src/client/streamableHttp.ts

@@ -29,6 +29,7 @@ import {
     isOAuthClientProvider,
     isStrictScopeSuperset,
     resolveAuthorizationCallbackParams,
+    rethrowTypedAuthFlowError,
     UnauthorizedError
 } from './auth';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced via {@linkcode} in finishAuth JSDoc
@@ -410,14 +411,20 @@ export class StreamableHTTPClientTransport implements Transport {
         // we must force a fresh authorization request.
         const forceReauthorization = isStrictScopeSuperset(unionScope, tokens?.scope);
 
-        return auth(this._oauthProvider, {
-            serverUrl: this._url,
-            resourceMetadataUrl: this._resourceMetadataUrl,
-            scope: unionScope,
-            forceReauthorization,
-            fetchFn: this._fetchWithInit,
-            skipIssuerMetadataValidation: this._skipIssuerMetadataValidation
-        });
+        try {
+            return await auth(this._oauthProvider, {
+                serverUrl: this._url,
+                resourceMetadataUrl: this._resourceMetadataUrl,
+                scope: unionScope,
+                forceReauthorization,
+                fetchFn: this._fetchWithInit,
+                skipIssuerMetadataValidation: this._skipIssuerMetadataValidation
+            });
+        } catch (error) {
+            // Untyped escapes from the step-up flow stay recognizable as auth
+            // failures — see rethrowTypedAuthFlowError.
+            rethrowTypedAuthFlowError(error, SdkErrorCode.ClientHttpForbidden);
+        }
     }
 
     private async _commonHeaders(): Promise<Headers> {