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

A stdio child that exits on the unrecognized server/discover probe is a
legacy signal, symmetric with the stdio probe-timeout rule: respawn the
child once via the transport's public close()/start() and run the plain
initialize handshake there. A transport the caller closed mid-probe is
never respawned, and an HTTP-class mid-probe close keeps rejecting with
the typed connect error. StdioClientTransport.start() clears the read
buffer so a dead predecessor's late flush cannot corrupt the next
child's first frame.

Author: felixweinberger

.changeset/probe-close-handling.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Handle a connection that closes during the `server/discover` version-negotiation probe. On stdio, a child that exits on the unrecognized probe is a legacy signal (symmetric with the stdio probe-timeout rule): under `versionNegotiation: { mode: 'auto' }` the client now respawns it once via the transport's own `close()`/`start()` and completes the plain `initialize` handshake there — stdio servers built on SDKs that terminate on any pre-`initialize` request (the official Rust SDK, rmcp) previously hard-failed under `'auto'`. A transport the caller closed mid-probe is never respawned, and on HTTP-class transports a mid-probe close keeps rejecting with the typed connect error. `StdioClientTransport.start()` now also clears the read buffer, so a dead predecessor's late flush cannot corrupt the next child's first frame.

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 child that exits on the unrecognized probe is a legacy server — stdio servers built on SDKs that terminate on any pre-`initialize` request (the official Rust SDK, rmcp) behave exactly this way — so under `'auto'` the client respawns the child once and falls back to `initialize` there: pre-connect `stderr` subscribers should re-read that getter after `connect()` resolves, and a pre-set `onclose` observer will see the probe child's close. A transport the caller closed during the probe is never respawned, and on HTTP a mid-probe close is ambiguous — never era evidence — so `connect()` rejects with the same typed `SdkError(EraNegotiationFailed)` 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)`.
 
 ::: warning

examples/cli-client/host/host.ts

@@ -513,11 +513,16 @@ export class McpHost {
                 cwd: entry.cwd,
                 stderr: 'pipe'
             });
-            transport.stderr?.on('data', (chunk: Buffer) => {
+            const logStderr = (chunk: Buffer) => {
                 const line = String(chunk).trim();
                 if (line) this.ui.serverLog(name, 'stderr', line);
-            });
+            };
+            const preConnectStderr = transport.stderr;
+            preConnectStderr?.on('data', logStderr);
             await client.connect(transport);
+            // Under 'auto', a legacy fallback may have respawned the child with a
+            // fresh stderr stream — re-read the getter and subscribe the new life.
+            if (transport.stderr !== preConnectStderr) transport.stderr?.on('data', logStderr);
         }
 
         try {

packages/client/src/client/probeClassifier.ts

@@ -48,6 +48,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 };
 
@@ -141,6 +143,18 @@ 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).
+                return { kind: 'legacy' };
+            }
+            // On HTTP a mid-probe close is an ambiguous network condition — the
+            // same typed connect error as any probe transport failure.
+            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 +267,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

@@ -103,6 +103,8 @@ export class StdioClientTransport implements Transport {
     private _readBuffer: ReadBuffer;
     private _serverParams: StdioServerParameters;
     private _stderrStream: PassThrough | null = null;
+    /** True after a local `close()` until the next `start()` — the negotiation layer's legacy-fallback respawn checks it so a caller's kill decision is never overridden. */
+    private _closedByCaller = false;
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -126,6 +128,14 @@ export class StdioClientTransport implements Transport {
             );
         }
 
+        this._closedByCaller = false;
+        // A dead predecessor's late flush must not prepend to the new child's first frame.
+        this._readBuffer.clear();
+        if (this._stderrStream?.writableEnded) {
+            // stderr: 'pipe' — the previous child's exit ended the stream; each life pipes into a fresh one.
+            this._stderrStream = new PassThrough();
+        }
+
         return new Promise((resolve, reject) => {
             this._process = spawn(this._serverParams.command, this._serverParams.args ?? [], {
                 // merge default env with server env because mcp server needs some env vars
@@ -183,6 +193,9 @@ export class StdioClientTransport implements Transport {
      * 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.
+     *
+     * Under `versionNegotiation: { mode: 'auto' }`, a legacy fallback may respawn the child with a
+     * fresh stream — re-read this getter after `connect()` resolves.
      */
     get stderr(): Stream | null {
         if (this._stderrStream) {
@@ -217,6 +230,7 @@ export class StdioClientTransport implements Transport {
     }
 
     async close(): Promise<void> {
+        this._closedByCaller = true;
         if (this._process) {
             const processToClose = this._process;
             this._process = undefined;

packages/client/src/client/versionNegotiation.ts

@@ -27,7 +27,7 @@ import {
 
 import { UnauthorizedError } from './auth';
 import type { ProbeEnvironment, ProbeOutcome, ProbeTransportKind, ProbeVerdict } from './probeClassifier';
-import { classifyProbeOutcome } from './probeClassifier';
+import { classifyProbeOutcome, describeError } from './probeClassifier';
 
 /**
  * Probe policy for `'auto'` and pinned negotiation modes.
@@ -71,7 +71,11 @@ export interface VersionNegotiationProbeOptions {
  *   outcome is definitive modern evidence. Network outage rejects with a typed
  *   connect error; a probe timeout falls back to `initialize` on stdio (a silent
  *   server on a local pipe is a legacy server) and rejects with a typed timeout
- *   error on HTTP (silence there is an outage).
+ *   error on HTTP (silence there is an outage). A connection closed mid-probe
+ *   follows the same split: on stdio a child that exits on the unrecognized
+ *   probe is a legacy server — the client respawns it once (`close()` +
+ *   `start()`) and runs `initialize` on the fresh child; on HTTP it rejects
+ *   with the same typed connect error as any probe transport failure.
  * - `{ pin: '<version>' }` — modern era at exactly the pinned revision: the
  *   connect-time `server/discover` must offer it. No fallback — anything else
  *   fails loudly with a typed error.
@@ -264,6 +268,16 @@ class ProbeWindow {
         });
     }
 
+    /**
+     * The legacy-fallback respawn opened a fresh connection: the forwarded
+     * mid-window close belonged to the previous life, so the successor's
+     * eventual close is a NEW event — detach()'s spent-close guard must not
+     * swallow it for the caller's pre-set observer.
+     */
+    noteRespawn(): void {
+        this._closeDelivered = false;
+    }
+
     /** Detach the window's handlers, restoring any the caller pre-set, leaving the transport's own `start` untouched. */
     detach(): void {
         this._pending = undefined;
@@ -339,7 +353,9 @@ function normalizeReply(reply: RawProbeReply, timeoutMs: number): ProbeOutcome {
             return { kind: 'network-error', error };
         }
         case 'closed': {
-            return { kind: 'network-error', error: new Error('Connection closed during the version negotiation probe') };
+            // Not folded into network-error: the classifier's closed row is
+            // transport-aware (stdio legacy signal vs typed error).
+            return { kind: 'closed' };
         }
         case 'timeout': {
             return { kind: 'timeout', timeoutMs };
@@ -437,6 +453,32 @@ export async function negotiateEra(
                                 'pre-2026-07-28 protocol version to fall back to'
                         );
                     }
+                    if (outcome.kind === 'closed') {
+                        // The probe consumed the connection (the child exited on
+                        // the unrecognized request): respawn via the public
+                        // lifecycle, then run the fallback handshake there. The
+                        // flag read happens BEFORE our own close() below — the
+                        // only close this path issues — and start() resets it,
+                        // so it can only be true when the CALLER closed
+                        // mid-probe: never override that kill decision.
+                        if ((deps.transport as { _closedByCaller?: boolean })._closedByCaller) {
+                            throw new SdkError(
+                                SdkErrorCode.EraNegotiationFailed,
+                                'Version negotiation failed: the transport was closed during the server/discover probe'
+                            );
+                        }
+                        try {
+                            await deps.transport.close();
+                            await deps.transport.start();
+                        } catch (error) {
+                            throw new SdkError(
+                                SdkErrorCode.EraNegotiationFailed,
+                                `Version negotiation failed: the transport could not restart for the legacy fallback: ${describeError(error)}`,
+                                { cause: error }
+                            );
+                        }
+                        window.noteRespawn();
+                    }
                     return { era: 'legacy' };
                 }
                 case 'error': {

packages/client/test/client/probeClassifier.test.ts

@@ -293,6 +293,22 @@ describe('row: timeout — transport-aware verdict', () => {
     });
 });
 
+describe('row: closed — transport-aware verdict, symmetric with the timeout row', () => {
+    test('stdio: a child that exits on the unrecognized probe is a legacy signal → legacy fallback', () => {
+        expect(classify({ kind: 'closed' }, { transportKind: 'stdio' })).toEqual({ kind: 'legacy' });
+    });
+
+    test('HTTP: a mid-probe close is ambiguous — the same typed connect error as any probe network failure', () => {
+        const verdict = classify({ kind: 'closed' }, { transportKind: 'http' });
+        expect(verdict.kind).toBe('error');
+        if (verdict.kind === 'error') {
+            expect(verdict.error).toBeInstanceOf(SdkError);
+            expect((verdict.error as SdkError).code).toBe(SdkErrorCode.EraNegotiationFailed);
+            expect(verdict.error.message).toContain('Connection closed during the version negotiation probe');
+        }
+    });
+});
+
 describe('row: browser opaque CORS/preflight TypeError, PROBE PHASE ONLY → legacy fallback (F-7)', () => {
     test('browser environment + bare TypeError → legacy', () => {
         expect(classify({ kind: 'network-error', error: new TypeError('Failed to fetch') }, { environment: 'browser' })).toEqual({

packages/client/test/client/stdio.test.ts

@@ -99,6 +99,61 @@ test('should respect custom maxBufferSize option', async () => {
     await closed;
 });
 
+test("a dead child's late stdout flush landing between close() and start() cannot poison the next life's first frame", async () => {
+    // The grandchild inherits (and so holds open) the child's stdout pipe and
+    // writes a stale partial frame into it AFTER close() returned: close()
+    // races its 2s teardown wait, sees the child already exited, and returns
+    // with the pipe still held, so the flush lands in the shared read buffer
+    // between close() and the next start(). start() clears the buffer, so the
+    // next life's first JSON-RPC line cannot parse as <stale><json>.
+    const FLUSHING_SERVER_SCRIPT = String.raw`
+        const { spawn } = require('child_process');
+        spawn(process.execPath, ['-e', "setTimeout(() => process.stdout.write('stale:'), 2400); setTimeout(() => {}, 4000);"], {
+            stdio: 'inherit'
+        });
+        let buffer = '';
+        process.stdin.on('data', chunk => {
+            buffer += chunk.toString();
+            let index;
+            while ((index = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                if (line.trim() === '') continue;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                } catch {
+                    continue;
+                }
+                if (message.method === 'whoami' && message.id !== undefined) {
+                    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, result: { pid: process.pid } }) + '\n');
+                }
+            }
+        });
+        process.stdin.on('end', () => process.exit(0));
+    `;
+    const transport = new StdioClientTransport({ command: process.execPath, args: ['-e', FLUSHING_SERVER_SCRIPT] });
+
+    await transport.start();
+    await transport.close();
+
+    // Let the predecessor's stale flush land in the close()->start() window.
+    await new Promise(resolve => setTimeout(resolve, 700));
+
+    await transport.start();
+    const reply = await new Promise<JSONRPCMessage>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('whoami timed out — stale residue poisoned the frame')), 5000);
+        transport.onmessage = message => {
+            clearTimeout(timer);
+            resolve(message);
+        };
+        transport.send({ jsonrpc: '2.0', id: 1, method: 'whoami' }).catch(reject);
+    });
+    expect(reply).toMatchObject({ id: 1, result: { pid: transport.pid } });
+
+    await transport.close();
+}, 15_000);
+
 test('should fire onerror and close when ReadBuffer overflows', async () => {
     const client = new StdioClientTransport({
         command: 'node',