fix(client): handle connection close during the version negotiation probe

A connection that closed while the server/discover probe awaited its
reply was a hard, untyped negotiation failure with no fallback. Stdio
servers built on SDKs that terminate on any pre-initialize request
(the official Rust SDK, rmcp, is the prominent example) connect fine
under mode 'legacy' but hard-failed under 'auto'.

- stdio: a server-side close during the probe is now a legacy signal,
  symmetric with the stdio probe-timeout rule. The stream died with the
  process, so the probe window leaves the transport's start() live and
  the Protocol.connect() handover restarts it (StdioClientTransport
  respawns from its retained parameters); the plain initialize fallback
  runs on the respawned process, byte-identical to a legacy connect.
- HTTP-class: a mid-probe close stays an error (never era evidence) but
  is now typed: SdkErrorCode.EraProbeConnectionClosed, a stable caller
  predicate instead of message-sniffing.
- A close initiated on the local side (transport.close() during the
  probe, caller shutdown or transport error recovery) gets the typed
  error on every transport: a local close never restarts the server.
- A restart that itself fails (respawn error, or a stdio-shaped custom
  transport whose start() cannot run again) rejects with a typed
  EraNegotiationFailed carrying the underlying error as data.cause.
- StdioClientTransport clears its read buffer on child exit so a
  restarted transport starts with a clean stream.
- Pin-mode and modern-only failures name the mid-probe close instead of
  implying the server answered the probe.

Author: felixweinberger

.changeset/probe-close-handling.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+---
+
+Handle a connection that closes during the `server/discover` version-negotiation probe instead of dead-ending in an untyped failure.
+
+On stdio, a server process that exits on the unrecognized probe is now classified as a legacy signal — symmetric with the stdio probe-timeout rule. Stdio servers built on SDKs that terminate on any pre-`initialize` request (the official Rust SDK, rmcp, is the prominent example) previously connected fine under `mode: 'legacy'` but hard-failed under `mode: 'auto'`; the client now restarts the transport (`StdioClientTransport.start()` respawns the server from its retained parameters, exactly what a `mode: 'legacy'` connect would have done) and completes the plain `initialize` handshake there. The respawned process sees bytes identical to a plain legacy connect.
+
+On HTTP-class transports a mid-probe close stays an error — an ambiguous network condition is never era evidence — but is now typed: `SdkError` with the new `SdkErrorCode.EraProbeConnectionClosed`, giving callers a stable predicate instead of message-sniffing the previous generic `EraNegotiationFailed` wrapper. A close initiated on the local side (`transport.close()` during the probe — a caller shutdown, or the transport's own error recovery) gets the same typed error on every transport: a local close never restarts the server. A restart that itself fails (respawn error, or a stdio-shaped custom transport whose `start()` cannot run again) rejects with a typed `EraNegotiationFailed` carrying the underlying error as `data.cause`.
+
+`StdioClientTransport` also clears its read buffer when the child process exits, so a restarted transport never sees a trailing partial line from the dead process. Known limitation: with `stderr: 'pipe'`, the `stderr` stream ends when the first process exits and does not carry a restarted process's output.

docs/protocol-versions.md

@@ -95,6 +95,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 the same stream; 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.
 
+A connection that closes mid-probe follows the same transport split. On stdio a server process that exits on the unrecognized probe is a legacy server — stdio servers built on SDKs that terminate on any pre-`initialize` request behave exactly this way (the official Rust SDK, rmcp, is the prominent example) — so `connect()` restarts the transport, respawning the server, and falls back to `initialize` there; the respawned process sees the same bytes a `mode: 'legacy'` connect would have sent. On HTTP a mid-probe close is ambiguous — a proxy drop or a crash, never era evidence — so `connect()` rejects with the typed `SdkError(EraProbeConnectionClosed)`.
+
 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)`.
 
 ::: warning

packages/client/src/client/client.ts

@@ -1077,11 +1077,35 @@ export class Client extends Protocol<ClientContext> {
             throw error;
         }
 
-        await super.connect(transport);
+        const restart = result.era === 'legacy' && result.restart === true;
+        try {
+            // On the stdio close-fallback (`restart`), negotiateEra left the
+            // transport's start() live, so this connect's unconditional start()
+            // genuinely restarts it — respawning the server process, exactly
+            // what a plain legacy connect does. Everywhere else start() is the
+            // armed one-shot pass-through.
+            await super.connect(transport);
+        } catch (error) {
+            if (!restart) throw error;
+            // A failed restart is a negotiation-phase failure: surface it with
+            // the typed contract every other negotiation failure has (the
+            // pre-restart behavior for a mid-probe close), not a raw transport
+            // error — e.g. a respawn spawn failure, or a stdio-shaped custom
+            // transport whose start() cannot run again after close.
+            await transport.close().catch(() => {});
+            throw new SdkError(
+                SdkErrorCode.EraNegotiationFailed,
+                'Version negotiation failed: the transport could not be restarted for the legacy fallback after the ' +
+                    `connection closed during the probe: ${error instanceof Error ? error.message : String(error)}`,
+                { cause: error }
+            );
+        }
 
         if (result.era === 'legacy') {
             // Conservative fallback: the plain legacy handshake on the SAME
-            // connection (the probe never touched the transport version slot).
+            // connection (the probe never touched the transport version slot) —
+            // or, on the stdio close-fallback, on the transport just restarted
+            // above (see the probe classifier's closed row for the rationale).
             await this._legacyHandshake(transport, options);
             return;
         }

packages/client/src/client/probeClassifier.ts

@@ -2,7 +2,8 @@
  * Probe outcome classifier (pure module): maps the outcome of the connect-time
  * `server/discover` probe onto one of four verdicts — modern era, the
  * spec-mandated `-32022` corrective continuation, legacy fallback (the plain
- * 2025 `initialize` handshake on the same connection), or a typed connect error.
+ * 2025 `initialize` handshake — on the same connection, or on a restarted
+ * transport when a stdio close consumed it), 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
@@ -48,6 +49,14 @@ export type ProbeOutcome =
     | { kind: 'network-error'; error: unknown }
     /** The transport's auth flow challenged during the probe send (`UnauthorizedError`). */
     | { kind: 'auth-required'; error: Error }
+    /**
+     * The transport reported close while the probe awaited its reply.
+     * `localClose` is true when the close was initiated on the local side —
+     * `transport.close()` ran during the probe window, whether from a caller
+     * shutdown/abort or the transport's own error recovery — and is therefore
+     * never a server-side signal.
+     */
+    | { kind: 'closed'; localClose?: boolean }
     /** No response arrived within the probe timeout. */
     | { kind: 'timeout'; timeoutMs: number };
 
@@ -82,8 +91,15 @@ export type ProbeVerdict =
      * arms a loop guard on the second rejection, throwing `error`.
      */
     | { kind: 'corrective'; version: string; error: UnsupportedProtocolVersionError }
-    /** Definitive legacy signal or unrecognized shape: perform the plain legacy `initialize` handshake on the same connection. */
-    | { kind: 'legacy' }
+    /**
+     * Definitive legacy signal or unrecognized shape: perform the plain legacy
+     * `initialize` handshake on the same connection. `restart` marks the one
+     * row where the same connection no longer exists (stdio close): the
+     * handshake runs on a restarted transport instead — for the stdio
+     * transport, `start()` respawns the server process, which is exactly what
+     * a `mode: 'legacy'` connect would have done.
+     */
+    | { kind: 'legacy'; restart?: true }
     /** Typed connect error — never converted to an era verdict. */
     | { kind: 'error'; error: Error };
 
@@ -125,6 +141,39 @@ export function classifyProbeOutcome(outcome: ProbeOutcome, context: ProbeClassi
             // handshake an auth-gated modern server as legacy.
             return { kind: 'error', error: outcome.error };
         }
+        case 'closed': {
+            if (outcome.localClose) {
+                // The local side closed the transport mid-probe — a caller
+                // shutdown/abort, or the transport's own error recovery (e.g.
+                // read-buffer overflow). Never era evidence on any transport,
+                // and on stdio it must not respawn a process the local side
+                // chose to terminate.
+                return {
+                    kind: 'error',
+                    error: new SdkError(
+                        SdkErrorCode.EraProbeConnectionClosed,
+                        'Connection closed locally during the version negotiation probe'
+                    )
+                };
+            }
+            if (context.transportKind === 'stdio') {
+                // A stdio child that exits on the unrecognized probe instead of
+                // answering is a legacy signal — the same backward-compatibility
+                // rule as the timeout row below (SDKs like the official Rust one
+                // terminate the server on ANY pre-initialize request). The
+                // stream died with the process, so the fallback cannot run on
+                // the same connection: `restart` has the caller run `initialize`
+                // on a restarted transport.
+                return { kind: 'legacy', restart: true };
+            }
+            // On HTTP a mid-probe close is an ambiguous network condition
+            // (proxy drop, crash, redeploy) — a typed connect error, never an
+            // era verdict.
+            return {
+                kind: 'error',
+                error: new SdkError(SdkErrorCode.EraProbeConnectionClosed, 'Connection closed during the version negotiation probe')
+            };
+        }
         case 'timeout': {
             if (context.transportKind === 'stdio') {
                 // Per the stdio transport's backward-compatibility rule, a probe

packages/client/src/client/stdio.ts

@@ -118,6 +118,14 @@ export class StdioClientTransport implements Transport {
 
     /**
      * Starts the server process and prepares to communicate with it.
+     *
+     * After the child process exits (`onclose`), `start()` may be called
+     * again: a fresh process is spawned from the same
+     * {@linkcode StdioServerParameters}. The client's version-negotiation
+     * close-fallback relies on this to run the legacy handshake after a
+     * server exits on the connect-time probe. Known limitation: with
+     * `stderr: 'pipe'`, the {@linkcode stderr} stream ends when the first
+     * process exits and does not carry a restarted process's output.
      */
     async start(): Promise<void> {
         if (this._process) {
@@ -150,6 +158,8 @@ export class StdioClientTransport implements Transport {
 
             this._process.on('close', _code => {
                 this._process = undefined;
+                // Drop any partial trailing line so a restarted transport starts with a clean stream.
+                this._readBuffer.clear();
                 this.onclose?.();
             });