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,
InsufficientScopeError, the 401-after-re-authentication diagnostic)
instead of flattening them into the generic HTTP row.

Fixes #2561

Author: felixweinberger

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

@@ -0,0 +1,16 @@
+---
+'@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 — 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 (`InsufficientScopeError`, the
+401-after-re-authentication diagnostic) instead of a legacy verdict or a
+generic negotiation wrap.

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; with one, the transport's auth flow runs first and its outcome propagates unchanged — `UnauthorizedError` for `finishAuth()`, or the flow's own typed failure (an `InsufficientScopeError`, the 401-after-re-authentication diagnostic).
+
 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)`.

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/versionNegotiation.ts

@@ -26,6 +26,7 @@ import {
 } from '@modelcontextprotocol/core-internal';
 
 import { UnauthorizedError } from './auth';
+import { OAuthClientFlowError } from './authErrors';
 import type { ProbeEnvironment, ProbeOutcome, ProbeTransportKind, ProbeVerdict } from './probeClassifier';
 import { classifyProbeOutcome } from './probeClassifier';
 
@@ -381,23 +382,38 @@ function normalizeReply(reply: RawProbeReply, timeoutMs: number): ProbeOutcome {
         }
         case 'send-error': {
             const error = reply.error;
-            if (error instanceof SdkHttpError) {
-                const text = (error.data as { text?: unknown } | undefined)?.text;
-                return { kind: 'http-error', status: error.data.status, body: typeof text === 'string' ? text : undefined };
-            }
-            const isUnauthorized =
+            const isAuthFlowError =
                 error instanceof UnauthorizedError ||
                 // Name fallback for auth errors the brand cannot reach: an
                 // UnauthorizedError from a differently bundled SDK copy at a
                 // skewed version, or an auth middleware's own class.
-                (error instanceof Error && error.name === 'UnauthorizedError');
-            if (isUnauthorized) {
-                // Auth-gated server. (The pre-branding name-string check alone
-                // could never fire for the SDK's own class — it did not set
-                // `.name` — so these send failures fell through to the generic
-                // network-error wrap.)
+                (error instanceof Error && error.name === 'UnauthorizedError') ||
+                // The transport's OAuth flow failing with its own typed error
+                // (e.g. InsufficientScopeError when a 403 insufficient_scope
+                // challenge has no provider to drive step-up).
+                error instanceof OAuthClientFlowError ||
+                // The transport's auth flow exhausting itself: 401 after the
+                // onUnauthorized re-auth retry, 403 after the step-up retry
+                // limit. Flattening these to the http-error row would swallow
+                // their codes and diagnostics.
+                (error instanceof SdkHttpError &&
+                    (error.code === SdkErrorCode.ClientHttpAuthentication || error.code === SdkErrorCode.ClientHttpForbidden));
+            if (isAuthFlowError) {
+                // Auth-gated server: propagate unchanged. (The pre-branding
+                // name-string check alone could never fire for the SDK's own
+                // class — it did not set `.name` — so these send failures fell
+                // through to the generic network-error wrap.)
                 return { kind: 'auth-required', error: error as Error };
             }
+            if (error instanceof SdkHttpError) {
+                const text = (error.data as { text?: unknown } | undefined)?.text;
+                return {
+                    kind: 'http-error',
+                    status: error.data.status,
+                    body: typeof text === 'string' ? text : undefined,
+                    statusText: error.data.statusText
+                };
+            }
             return { kind: 'network-error', error };
         }
         case 'closed': {

packages/client/test/client/probeFixtureCorpus.test.ts

@@ -19,7 +19,7 @@
  * probe wire shape (string id, `server/discover` first, never a real request).
  */
 import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/core-internal';
-import { LATEST_PROTOCOL_VERSION, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core-internal';
+import { LATEST_PROTOCOL_VERSION, PROTOCOL_VERSION_META_KEY, SdkErrorCode, SdkHttpError } from '@modelcontextprotocol/core-internal';
 import { describe, expect, it } from 'vitest';
 
 import { Client } from '../../src/client/client';
@@ -161,6 +161,29 @@ const CORPUS: CorpusRow[] = [
         outcome: { kind: 'result', result: { content: [{ type: 'text', text: `supportedVersions: ["${MODERN}"]` }] } },
         expected: 'legacy'
     },
+    // --- Auth statuses are never era evidence (#2561): an auth-protected
+    // server is not a legacy server, whatever the body says — typed failure,
+    // never initialize (fallbackAvailable is true in every row here).
+    {
+        name: 'auth: HTTP 401 challenge (WWW-Authenticate rides the header; body carries the OAuth error JSON) → typed auth failure, never legacy',
+        outcome: { kind: 'http-error', status: 401, body: '{"error":"invalid_token","error_description":"Missing bearer token"}' },
+        expected: 'error'
+    },
+    {
+        name: 'auth: bare HTTP 401 (no body) → typed auth failure, never legacy',
+        outcome: { kind: 'http-error', status: 401 },
+        expected: 'error'
+    },
+    {
+        name: 'auth: bare HTTP 403 denial (no body) → typed auth failure, never legacy',
+        outcome: { kind: 'http-error', status: 403 },
+        expected: 'error'
+    },
+    {
+        name: 'auth: a 401 whose body parses as a JSON-RPC error is still an auth failure — the auth layer wrote that body, not server/discover',
+        outcome: { kind: 'http-error', status: 401, body: DEPLOYED_SESSION_REQUIRED_BODY },
+        expected: 'error'
+    },
     // --- Q12 transport-aware timeout rows (stdio falls back, HTTP stays a typed error).
     {
         name: 'timeout on stdio → legacy fallback (the stdio backward-compatibility rule)',
@@ -209,6 +232,25 @@ describe('T9/T11 merged probe fixture corpus (probe classifier)', () => {
         });
     }
 
+    it('the 401/403 typed failures name the auth status and carry it with the response text and reason phrase', () => {
+        for (const [status, statusText, body] of [
+            [401, 'Unauthorized', '{"error":"invalid_token"}'],
+            [403, 'Forbidden', 'nope']
+        ] as const) {
+            const verdict = classifyProbeOutcome({ kind: 'http-error', status, statusText, body }, baseContext);
+            expect(verdict.kind).toBe('error');
+            if (verdict.kind === 'error') {
+                expect(verdict.error).toBeInstanceOf(SdkHttpError);
+                const error = verdict.error as SdkHttpError;
+                expect(error.code).toBe(SdkErrorCode.EraNegotiationFailed);
+                expect(error.status).toBe(status);
+                expect(error.statusText).toBe(statusText);
+                expect(error.data.text).toBe(body);
+                expect(error.message).toContain(String(status));
+            }
+        }
+    });
+
     it('a DiscoverResult with a mutual version is the only result shape that yields a modern verdict', () => {
         const verdict = classifyProbeOutcome(
             {

packages/client/test/client/versionNegotiation.test.ts

@@ -14,11 +14,13 @@ import {
     PROTOCOL_VERSION_META_KEY,
     SdkError,
     SdkErrorCode,
+    SdkHttpError,
     UnsupportedProtocolVersionError
 } from '@modelcontextprotocol/core-internal';
 import { describe, expect, test } from 'vitest';
 
 import { UnauthorizedError } from '../../src/client/auth';
+import { InsufficientScopeError } from '../../src/client/authErrors';
 import { Client } from '../../src/client/client';
 import type { StreamableHTTPClientTransportOptions } from '../../src/client/streamableHttp';
 import type { StdioServerParameters } from '../../src/client/stdio';
@@ -1103,6 +1105,41 @@ describe('probe send-error classification', () => {
         expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(false);
     });
 
+    test("the transport's post-re-auth 401 (SdkHttpError ClientHttpAuthentication) propagates unchanged — not flattened to the http-error row", async () => {
+        const reason = new SdkHttpError(SdkErrorCode.ClientHttpAuthentication, 'Server returned 401 after re-authentication', {
+            status: 401,
+            statusText: 'Unauthorized'
+        });
+        const transport = new AuthGatedTransport(reason);
+        const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
+
+        const rejection = await client.connect(transport).then(
+            () => {
+                throw new Error('connect unexpectedly resolved');
+            },
+            (e: unknown) => e
+        );
+        // The same object, code and diagnostic intact — rebuilding it from the
+        // status alone would swallow the re-auth context.
+        expect(rejection).toBe(reason);
+        expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(false);
+    });
+
+    test('an OAuth flow error (InsufficientScopeError from a step-up challenge with no provider) propagates unchanged — no fallback, no network-error wrap', async () => {
+        const reason = new InsufficientScopeError({ requiredScope: 'mcp:tools' });
+        const transport = new AuthGatedTransport(reason);
+        const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
+
+        const rejection = await client.connect(transport).then(
+            () => {
+                throw new Error('connect unexpectedly resolved');
+            },
+            (e: unknown) => e
+        );
+        expect(rejection).toBe(reason);
+        expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(false);
+    });
+
     test('a plain send failure stays a typed negotiation error — no fallback runs', async () => {
         const transport = new AuthGatedTransport(new Error('connection refused'));
         const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });