fix(client): propagate UnauthorizedError from the negotiation probe instead of taking the legacy fallback

The scoped-tools example caught the previous commit classifying a probe-time
auth challenge as a plain HTTP 401, which routed to the conservative legacy
fallback: the fallback initialize re-triggered the transport's auth flow inside
the same connect() — a second authorization prompt whose PKCE verifier
overwrote the first — and would settle an auth-gated modern server on the
legacy era with no evidence.

An auth challenge is not era evidence and is not the probe's to absorb: add an
auth-required probe outcome that propagates the original UnauthorizedError
unchanged, so connect() rejects with it after exactly one authorization round —
the caller runs finishAuth() and reconnects, and the retry probes with the
token and settles the era for real. (Older releases surfaced the same challenge
wrapped as the data.cause of an SdkError(EraNegotiationFailed); callers that
unwrap keep working, as the oauth example shows.)

Examples e2e: 73/73 legs green, including scoped-tools http/modern.

Author: felixweinberger

.changeset/cross-bundle-error-instanceof.md

@@ -3,4 +3,4 @@
 '@modelcontextprotocol/server': patch
 ---
 
-`instanceof` on the SDK error classes (`ProtocolError` and its typed subclasses, `SdkError`/`SdkHttpError`, `OAuthError`, and the client's `SseError`, `UnauthorizedError`, and OAuth-client-flow error family — `OAuthClientFlowError` and its subclasses) now works across separately bundled copies of the SDK. The classes match by a stable brand (via `Symbol.hasInstance` and a registry symbol) instead of prototype identity, so a process that uses both `@modelcontextprotocol/client` and `@modelcontextprotocol/server` - a gateway, host, or in-process test - can check errors constructed by either package against the class re-exported by the other. Ordinary prototype-based `instanceof` is preserved as a fallback; user-defined subclasses keep plain prototype semantics. Notes: cross-bundle matching requires both copies to be at or after this release; brands assert identity, not field shape, across versions - keep reading fields defensively. As a side effect, a foreign-bundle `SdkError` used as an abort reason is now rethrown as-is instead of being wrapped as a `RequestTimeout`. Also: `UnauthorizedError` now sets `error.name` to `'UnauthorizedError'` (previously `'Error'`), and per-package conformance tests enforce that every exported error class participates in branding. Version-negotiation probing now recognizes `UnauthorizedError` (previously a dead name-string check) and classifies an auth-gated server as an HTTP 401 outcome — taking the conservative legacy fallback instead of failing negotiation with a network error.
+`instanceof` on the SDK error classes (`ProtocolError` and its typed subclasses, `SdkError`/`SdkHttpError`, `OAuthError`, and the client's `SseError`, `UnauthorizedError`, and OAuth-client-flow error family — `OAuthClientFlowError` and its subclasses) now works across separately bundled copies of the SDK. The classes match by a stable brand (via `Symbol.hasInstance` and a registry symbol) instead of prototype identity, so a process that uses both `@modelcontextprotocol/client` and `@modelcontextprotocol/server` - a gateway, host, or in-process test - can check errors constructed by either package against the class re-exported by the other. Ordinary prototype-based `instanceof` is preserved as a fallback; user-defined subclasses keep plain prototype semantics. Notes: cross-bundle matching requires both copies to be at or after this release; brands assert identity, not field shape, across versions - keep reading fields defensively. As a side effect, a foreign-bundle `SdkError` used as an abort reason is now rethrown as-is instead of being wrapped as a `RequestTimeout`. Also: `UnauthorizedError` now sets `error.name` to `'UnauthorizedError'` (previously `'Error'`), and per-package conformance tests enforce that every exported error class participates in branding. Version-negotiation probing now recognizes `UnauthorizedError` (previously a dead name-string check) and propagates it unchanged, so `connect()` on an auth-gated server rejects with the original `UnauthorizedError` (previously wrapped as the `cause` of an `SdkError(EraNegotiationFailed)`) — run `finishAuth()` and reconnect, and the retry probes with the token.

examples/oauth/client.ts

@@ -113,11 +113,12 @@ let challenged = false;
 try {
     await client.connect(firstTransport);
 } catch (error) {
-    // Under `--legacy` the transport surfaces `UnauthorizedError` directly;
-    // under `mode: 'auto'` the version-negotiation probe is what got 401'd
-    // and wraps it in an EraNegotiationFailed `SdkError` whose `data.cause`
-    // is the original `UnauthorizedError`. Either way the auth driver has
-    // already run by the time we land here — DCR done, auth URL captured.
+    // Both `--legacy` and `mode: 'auto'` surface the original
+    // `UnauthorizedError` directly (the negotiation probe propagates it
+    // unchanged; older releases wrapped it as the `data.cause` of an
+    // EraNegotiationFailed `SdkError`, which the unwrap below still
+    // tolerates). Either way the auth driver has already run by the time we
+    // land here — DCR done, auth URL captured.
     const root = error instanceof UnauthorizedError ? error : (error as { data?: { cause?: unknown } }).data?.cause;
     if (!(root instanceof UnauthorizedError)) throw error;
     challenged = true;

packages/client/src/client/probeClassifier.ts

@@ -46,6 +46,8 @@ export type ProbeOutcome =
     /** The HTTP layer rejected the probe POST (non-2xx); `body` is the raw response text, when available. */
     | { kind: 'http-error'; status: number; body?: string }
     | { kind: 'network-error'; error: unknown }
+    /** The transport's auth flow challenged during the probe send (`UnauthorizedError`). */
+    | { kind: 'auth-required'; error: Error }
     /** No response arrived within the probe timeout. */
     | { kind: 'timeout'; timeoutMs: number };
 
@@ -114,6 +116,15 @@ export function classifyProbeOutcome(outcome: ProbeOutcome, context: ProbeClassi
         case 'network-error': {
             return classifyNetworkError(outcome.error, context);
         }
+        case 'auth-required': {
+            // Not era evidence: propagate the auth challenge unchanged so the
+            // caller can run finishAuth() and reconnect — the reconnect probes
+            // again with the token and settles the era with real evidence.
+            // Converting to a legacy fallback here would re-run the auth flow
+            // inside the same connect (a second authorization prompt) and then
+            // handshake an auth-gated modern server as legacy.
+            return { kind: 'error', error: outcome.error };
+        }
         case 'timeout': {
             if (context.transportKind === 'stdio') {
                 // Per the stdio transport's backward-compatibility rule, a probe

packages/client/src/client/versionNegotiation.ts

@@ -301,11 +301,11 @@ function normalizeReply(reply: RawProbeReply, timeoutMs: number): ProbeOutcome {
                 // skewed version, or an auth middleware's own class.
                 (error instanceof Error && error.name === 'UnauthorizedError');
             if (isUnauthorized) {
-                // Auth-gated server: not era evidence — the conservative legacy
-                // fallback re-runs the auth flow through the plain connect path.
-                // (The pre-branding name-string check alone could never fire
-                // for the SDK's own class — it did not set `.name`.)
-                return { kind: 'http-error', status: 401 };
+                // 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.)
+                return { kind: 'auth-required', error: error as Error };
             }
             return { kind: 'network-error', error };
         }

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

@@ -728,27 +728,42 @@ describe('probe send-error classification', () => {
         }
     }
 
-    test('UnauthorizedError from the probe send is an auth-gated server — legacy fallback on the same connection', async () => {
-        const transport = new AuthGatedTransport(new UnauthorizedError());
+    test('UnauthorizedError from the probe send propagates unchanged — no fallback, no second auth round (finishAuth + reconnect probes again)', async () => {
+        const reason = new UnauthorizedError();
+        const transport = new AuthGatedTransport(reason);
         const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
 
-        await client.connect(transport);
+        const rejection = await client.connect(transport).then(
+            () => {
+                throw new Error('connect unexpectedly resolved');
+            },
+            (e: unknown) => e
+        );
 
-        expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(true);
-        expect(client.getNegotiatedProtocolVersion()).toBe('2025-11-25');
+        // The original error, unwrapped: callers dispatch finishAuth() on it.
+        expect(rejection).toBe(reason);
+        // No initialize fallback ran — that would re-trigger the transport's
+        // auth flow (a second authorization prompt) and pin an auth-gated
+        // modern server to the legacy era.
+        expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(false);
     });
 
-    test("a foreign auth error matching only by name === 'UnauthorizedError' also takes the legacy fallback", async () => {
+    test("a foreign auth error matching only by name === 'UnauthorizedError' propagates the same way", async () => {
         class ForeignUnauthorizedError extends Error {
             override readonly name = 'UnauthorizedError';
         }
-        const transport = new AuthGatedTransport(new ForeignUnauthorizedError('401 from middleware'));
+        const reason = new ForeignUnauthorizedError('401 from middleware');
+        const transport = new AuthGatedTransport(reason);
         const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
 
-        await client.connect(transport);
-
-        expect(requests(transport.sent).some(r => r.method === 'initialize')).toBe(true);
-        expect(client.getNegotiatedProtocolVersion()).toBe('2025-11-25');
+        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 () => {