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

A stdio server that exits on the unrecognized server/discover probe (the
rmcp shape: terminate on any pre-initialize request) connected fine under
mode 'legacy' but hard-failed under mode 'auto'. Classify that close as a
legacy signal, symmetric with the stdio probe-timeout rule.

StdioClientTransport owns the restart: an internal capability respawns the
server after the child died, with generation-scoped child event handlers,
the read buffer cleared on child exit, and refusal after a local close();
with stderr 'pipe' the aggregate stream spans restarts and ends exactly
once, in close(). The probe layer checks for the capability and asks the
transport to restart before running the plain initialize fallback; a
transport without it, or whose restart refuses or fails, rejects with the
existing typed negotiation error. On HTTP a mid-probe close keeps
surfacing as the same typed connect error as any probe transport failure.

Author: felixweinberger

.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 — `start()` opens a generation and `close()` retires it, so a dead child's late events can touch neither a successor nor a closed transport — 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, and a `start()` after `close()` begins a fresh stream.

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 process from 'node:process';
 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,21 @@ export function getDefaultEnvironment(): Record<string, string> {
  *
  * 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. `start()` opens a
+     * generation and `close()` retires it, so a locally-closed child's late
+     * events (a SIGKILLed child's trailing stdout flush, its eventual 'close')
+     * are inert — close() already performed the cleanup itself.
+     */
+    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 +128,26 @@ export class StdioClientTransport implements Transport {
 
     /**
      * 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 +158,39 @@ export class StdioClientTransport implements Transport {
                 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 +200,41 @@ export class StdioClientTransport implements Transport {
                 }
             });
 
-            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. A `start()` after
+     * `close()` begins a new life with a fresh stream: re-read this getter after that `start()`
+     * (no output is lost — the fresh stream buffers until read).
      */
     get stderr(): Stream | null {
         if (this._stderrStream) {
@@ -217,8 +269,9 @@ export class StdioClientTransport implements Transport {
     }
 
     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 +308,18 @@ export class StdioClientTransport implements Transport {
         }
 
         this._readBuffer.clear();
+        // Retire the generation AFTER the teardown waits: a child that exited
+        // during them delivered its 'close' (and onclose) normally; anything
+        // still in flight past this point belongs to a closed life.
+        this._generation++;
+
+        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> {