fix(client): recover from connection close during the version-negotiation probe

.changeset/probe-close-handling.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+---
+
+Handle a connection that closes during the `server/discover` version-negotiation probe.
+
+On stdio, a server process that exits on the unrecognized probe is a legacy signal — symmetric with the stdio probe-timeout rule. 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'`; `StdioClientTransport` now restarts itself (respawning the server from its retained parameters) and the client completes the plain `initialize` handshake there — the respawned process sees bytes identical to a plain legacy connect. A transport that was closed locally, or that cannot restart, rejects with a typed negotiation error instead: a deliberately terminated server is never resurrected. On HTTP-class transports a mid-probe close keeps surfacing as the same typed connect error as any other probe transport failure — an ambiguous drop is never era evidence.
+
+`StdioClientTransport` restart mechanics: child events are generation-scoped (a slow-dying child's late events cannot touch its successor), the read buffer is cleared on child exit, and with `stderr: 'pipe'` the stream spans restarts — it ends exactly once, on `close()`, not on a child's exit.

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

@@ -78,8 +78,16 @@ error. Probe timeouts are **transport-aware**: on **stdio** a server that does n
 answer within `timeoutMs` is treated as legacy and the client falls back to `initialize`
 on the same stream (some legacy servers never respond to unknown pre-`initialize`
 requests at all); on **HTTP** a probe timeout rejects with `SdkError(RequestTimeout)` —
-a dead HTTP server is never misreported as legacy. One browser-specific exception: an
-opaque CORS/preflight `TypeError` during the probe falls back to the legacy era, because
+a dead HTTP server is never misreported as legacy. A mid-probe **connection close** is
+transport-aware the same way: on **stdio** a server process that exits on the
+unrecognized probe is treated as legacy — the transport restarts itself (respawning
+the server) and the client falls back to `initialize` there (stdio servers built on
+SDKs that terminate on any pre-`initialize` request behave this way); on **HTTP** a
+mid-probe close rejects with the same typed connect error as any probe transport
+failure (`SdkError(EraNegotiationFailed)`) — an ambiguous drop is never misreported
+as legacy. A transport closed locally during the probe is never restarted: `connect()`
+rejects with the same typed error. One browser-specific exception: an opaque
+CORS/preflight `TypeError` during the probe falls back to the legacy era, because
 deployed 2025 servers commonly have CORS allow-lists that predate the 2026 headers.
 
 ```typescript

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 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 the transport restarts itself, respawning the server, and `connect()` 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 same typed `SdkError(EraNegotiationFailed)` as any probe transport failure. A transport closed locally during the probe is never restarted.
+
 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/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,8 @@ 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. */
+    | { kind: 'closed' }
     /** No response arrived within the probe timeout. */
     | { kind: 'timeout'; timeoutMs: number };
 
@@ -82,8 +85,13 @@ 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 needs the transport restarted first.
+     */
+    | { kind: 'legacy'; restart?: true }
     /** Typed connect error — never converted to an era verdict. */
     | { kind: 'error'; error: Error };
 
@@ -141,6 +149,21 @@ export function classifyProbeOutcome(outcome: ProbeOutcome, context: ProbeClassi
             // handshake an auth-gated modern server as legacy.
             return { kind: 'error', error: outcome.error };
         }
+        case 'closed': {
+            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 needs the
+                // transport restarted.
+                return { kind: 'legacy', restart: true };
+            }
+            // On HTTP a mid-probe close is an ambiguous network condition
+            // (proxy drop, crash, redeploy) — the same typed connect error as
+            // any probe transport failure, never an era verdict.
+            return classifyNetworkError(new Error('Connection closed during the version negotiation probe'), context);
+        }
         case 'timeout': {
             if (context.transportKind === 'stdio') {
                 // Per the stdio transport's backward-compatibility rule, a probe
@@ -253,7 +276,8 @@ function isOpaqueFetchTypeError(error: unknown): boolean {
     return error instanceof TypeError || (error instanceof Error && error.name === 'TypeError');
 }
 
-function describeError(error: unknown): string {
+/** Human-readable rendering of an unknown thrown value for probe diagnostics. */
+export function describeError(error: unknown): string {
     return error instanceof Error ? error.message : String(error);
 }
 

packages/client/src/client/stdio.ts

@@ -3,8 +3,8 @@
 import type { Stream } from 'node:stream';
 import { PassThrough } from 'node:stream';
 
-import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/core-internal';
-import { ReadBuffer, SdkError, SdkErrorCode, serializeMessage } from '@modelcontextprotocol/core-internal';
+import type { JSONRPCMessage, RestartableTransport } from '@modelcontextprotocol/core-internal';
+import { ReadBuffer, SdkError, SdkErrorCode, serializeMessage, TRANSPORT_RESTART } from '@modelcontextprotocol/core-internal';
 import spawn from 'cross-spawn';
 
 export type StdioServerParameters = {
@@ -98,11 +98,15 @@
  *
  * This transport is only available in Node.js environments.
  */
-export class StdioClientTransport implements Transport {
+export class StdioClientTransport implements RestartableTransport {
     private _process?: ChildProcess;
     private _readBuffer: ReadBuffer;
     private _serverParams: StdioServerParameters;
     private _stderrStream: PassThrough | null = null;
+    /** Monotonic child generation; every child's event handlers check it so a dead child's late events cannot touch a successor. */
+    private _generation = 0;
+    /** `true` after a local {@linkcode close} (caller shutdown or the transport's own error recovery); cleared by {@linkcode start}. */
+    private _closedLocally = false;
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -118,16 +122,26 @@
 
     /**
      * Starts the server process and prepares to communicate with it.
+     *
+     * After the child process exits, `start()` may be called again: a fresh
+     * process is spawned from the same {@linkcode StdioServerParameters}.
      */
     async start(): Promise<void> {
         if (this._process) {
             throw new Error(
                 'StdioClientTransport already started! If using Client class, note that connect() calls start() automatically.'
             );
         }
+        this._closedLocally = false;
+        if (this._stderrStream?.writableEnded) {
+            // close() ended the previous life's aggregate stream; a caller
+            // start() after close() begins a new life with a fresh stream.
+            this._stderrStream = new PassThrough();
+        }
+        const generation = ++this._generation;
 
         return new Promise((resolve, reject) => {
-            this._process = spawn(this._serverParams.command, this._serverParams.args ?? [], {
+            const proc = spawn(this._serverParams.command, this._serverParams.args ?? [], {
                 // merge default env with server env because mcp server needs some env vars
                 env: {
                     ...getDefaultEnvironment(),
@@ -138,26 +152,39 @@
                 windowsHide: process.platform === 'win32',
                 cwd: this._serverParams.cwd
             });
+            this._process = proc;
 
-            this._process.on('error', error => {
+            proc.on('error', error => {
                 reject(error);
-                this.onerror?.(error);
+                if (this._generation === generation) {
+                    this.onerror?.(error);
+                }
             });
 
-            this._process.on('spawn', () => {
+            proc.on('spawn', () => {
                 resolve();
             });
 
-            this._process.on('close', _code => {
+            proc.on('close', _code => {
+                if (this._generation !== generation) {
+                    return;
+                }
                 this._process = undefined;
+                // Drop any partial trailing line so a restarted transport starts with a clean stream.
+                this._readBuffer.clear();
                 this.onclose?.();
             });
 
-            this._process.stdin?.on('error', error => {
-                this.onerror?.(error);
+            proc.stdin?.on('error', error => {
+                if (this._generation === generation) {
+                    this.onerror?.(error);
+                }
             });
 
-            this._process.stdout?.on('data', chunk => {
+            proc.stdout?.on('data', chunk => {
+                if (this._generation !== generation) {
+                    return;
+                }
                 try {
                     this._readBuffer.append(chunk);
                     this.processReadBuffer();
@@ -167,22 +194,39 @@
                 }
             });
 
-            this._process.stdout?.on('error', error => {
-                this.onerror?.(error);
+            proc.stdout?.on('error', error => {
+                if (this._generation === generation) {
+                    this.onerror?.(error);
+                }
             });
 
-            if (this._stderrStream && this._process.stderr) {
-                this._process.stderr.pipe(this._stderrStream);
+            if (this._stderrStream && proc.stderr) {
+                // end: false — the aggregate stream spans children; it ends in close(), never on a child's exit.
+                proc.stderr.pipe(this._stderrStream, { end: false });
             }
         });
     }
 
+    /**
+     * Version-negotiation close-fallback (internal, keyed by
+     * `TRANSPORT_RESTART`): respawn the server after the child died out from
+     * under the connection. Refuses after a local {@linkcode close} — a
+     * deliberately terminated server is never resurrected.
+     */
+    async [TRANSPORT_RESTART](): Promise<void> {
+        if (this._closedLocally) {
+            throw new Error('StdioClientTransport was closed locally; refusing to respawn the server process');
+        }
+        await this.start();
+    }
+
     /**
      * The `stderr` stream of the child process, if {@linkcode StdioServerParameters.stderr} was set to `"pipe"` or `"overlapped"`.
      *
      * If `stderr` piping was requested, a `PassThrough` stream is returned _immediately_, allowing callers to
      * attach listeners before the `start` method is invoked. This prevents loss of any early
-     * error output emitted by the child process.
+     * error output emitted by the child process. The stream spans restarts — a child's exit
+     * never ends it; it ends exactly once, when {@linkcode close} is called.
      */
     get stderr(): Stream | null {
         if (this._stderrStream) {
@@ -217,8 +261,9 @@
     }
 
     async close(): Promise<void> {
-        if (this._process) {
-            const processToClose = this._process;
+        this._closedLocally = true;
+        const processToClose = this._process;
+        if (processToClose) {
             this._process = undefined;
 
             const closePromise = new Promise<void>(resolve => {
@@ -255,6 +300,14 @@
         }
 
         this._readBuffer.clear();
+
+        if (this._stderrStream !== null && !this._stderrStream.writableEnded) {
+            // The aggregate stderr stream ends exactly once, here. Unpipe first:
+            // a SIGKILLed child may still flush after we gave up waiting, and a
+            // write to an ended stream would error.
+            processToClose?.stderr?.unpipe(this._stderrStream);
+            this._stderrStream.end();
+        }
     }
 
     send(message: JSONRPCMessage): Promise<void> {