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 it
once with a fresh transport start() (the probe's close event already
tore the connection down) and run the plain initialize handshake there.
The respawn is gated on a close-provenance stamp (well-known symbol in a
leaf module, implemented by StdioClientTransport): a transport the
caller closed mid-probe, or one that does not report provenance, rejects
with the typed connect error naming the close, and HTTP-class mid-probe
closes keep rejecting typed. Transport hygiene: start() clears the read
buffer and scopes child event handlers per life so a dead predecessor's
deferred events cannot touch a successor; close() unpipes the child's
stderr after teardown and always ends the aggregate stream (also for a
never-started transport); a respawned life whose predecessor's stream
was never read drops stderr instead of buffering toward backpressure.

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 a fresh transport `start()` — the probe's close event already tore the connection down — and completes the plain `initialize` handshake there (the exit must close the child's stdio pipes to register as a close; an exit hidden behind a helper process holding them open falls to the probe-timeout path instead) — stdio servers built on SDKs that terminate on any pre-`initialize` request (the official Rust SDK, rmcp) previously hard-failed under `'auto'`. The respawn happens only for transports that positively report close provenance (an internal well-known-symbol stamp implemented by `StdioClientTransport`): a transport the caller closed mid-probe, or a custom transport that does not track provenance, rejects with the typed connect error instead — and on HTTP-class transports a mid-probe close keeps rejecting with the typed connect error. `StdioClientTransport` hygiene: `start()` clears the read buffer and scopes child event handlers per life, so a dead predecessor's deferred `close`/stdout events can no longer touch a successor after a `close()` → `start()` restart; `close()` detaches the child's stderr pipe and ends the aggregate stream once teardown completes — also for a never-started transport — so a dead predecessor cannot corrupt the next child's first frame, `stderr` readers of a closed transport always see `end`, and a restarted life begins on a fresh stream (re-read the `stderr` getter; a fresh stream nobody ever read drops output instead of buffering toward backpressure).

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

@@ -82,6 +82,17 @@ a dead HTTP server is never misreported as legacy. One browser-specific exceptio
 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.
 
+A mid-probe **connection close** follows the same transport split: on **stdio** a child
+that exits on the unrecognized probe is a legacy signal — the client respawns it once
+(transports that positively report close provenance only, as `StdioClientTransport`
+does; the exit must close the child's stdio pipes to register, else the probe-timeout
+path applies) and falls back to `initialize` on the fresh child; pre-connect `stderr`
+subscribers re-read that getter after `connect()`, and a pre-set `onclose` observer
+sees the probe child's close. On **HTTP** a mid-probe close rejects with the same typed
+`SdkError(EraNegotiationFailed)` as any probe transport failure. (The era-independent
+stderr end-of-stream change is described in the
+[stdio transport section of the v2 upgrade guide](./upgrade-to-v2.md#stdio-transport).)
+
 ```typescript
 versionNegotiation: {
     mode: 'auto',

docs/migration/upgrade-to-v2.md

@@ -1581,6 +1581,12 @@ rewrite required unless noted.
   pending — now reject the pending `send()` and close the transport through
   `onerror`/`onclose` instead of surfacing an unhandled stream error; lifecycle
   tests that pinned a crash-class exit observe a clean shutdown instead.
+- With `stderr: 'pipe'`, `StdioClientTransport.close()` now ends the aggregate stderr
+  stream when its teardown completes (previously the stream ended only when the
+  child's own stderr closed — never, if that pipe outlived `close()`), and a
+  `start()` after `close()` begins a fresh stream — re-read the `stderr` getter, and
+  keep reading it: a fresh stream whose predecessor was being read buffers until
+  read and can eventually stall a chatty child on stderr backpressure.
 
 #### Client list methods
 

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 (the exit must close the child's stdio pipes to register as a close — an exit hidden behind a helper process holding them open falls to the probe-timeout path instead): 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. The respawn is limited to transports that positively report close provenance (the SDK's own `StdioClientTransport` does): a transport the caller closed during the probe (closed via `transport.close()` — killing the child process directly is outside the transport's API and indistinguishable from a server-side exit), or a custom stdio-shaped transport that does not track it, is never respawned — and on HTTP a mid-probe close is ambiguous, never era evidence — `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/closeProvenance.ts

@@ -0,0 +1,23 @@
+/**
+ * Close-provenance seam between the stdio transport and the negotiation
+ * engine — a deliberate leaf module: both sides import it without coupling
+ * the `/stdio` subpath's module graph to the negotiation engine (or vice
+ * versa). Internal — nothing here is part of the public surface.
+ */
+import type { Transport } from '@modelcontextprotocol/core-internal';
+
+/**
+ * Close-provenance contract: a transport opts into the legacy-fallback respawn
+ * by stamping `this[CLOSED_BY_CALLER] = false` in `start()` and `= true` at the
+ * top of `close()` — negotiation respawns only on a `false` stamp; a `true`
+ * stamp (local close) or an absent stamp (no provenance tracked) is never
+ * respawned. `Symbol.for`: one shared registry key across bundled SDK copies,
+ * no import needed to interoperate.
+ */
+export const CLOSED_BY_CALLER: unique symbol = Symbol.for('mcp.closedByCaller');
+
+/** Typed read of the {@linkcode CLOSED_BY_CALLER} stamp — `undefined` when the transport does not implement the contract. */
+export function closeProvenance(transport: Transport): boolean | undefined {
+    const value = (transport as { [CLOSED_BY_CALLER]?: unknown })[CLOSED_BY_CALLER];
+    return typeof value === 'boolean' ? value : undefined;
+}

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

@@ -7,6 +7,8 @@ import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/core-inter
 import { ReadBuffer, SdkError, SdkErrorCode, serializeMessage } from '@modelcontextprotocol/core-internal';
 import spawn from 'cross-spawn';
 
+import { CLOSED_BY_CALLER } from './closeProvenance';
+
 export type StdioServerParameters = {
     /**
      * The executable to run to start the server.
@@ -126,8 +128,25 @@ export class StdioClientTransport implements Transport {
             );
         }
 
+        // Close-provenance stamp (see CLOSED_BY_CALLER): a fresh life has not been closed locally.
+        (this as { [CLOSED_BY_CALLER]?: boolean })[CLOSED_BY_CALLER] = 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 life's stream was ended (by its natural death, or by
+            // close() completing teardown): this life pipes into a fresh one. Re-read the getter.
+            const prior = this._stderrStream;
+            this._stderrStream = new PassThrough();
+            if (prior.readableFlowing === null && prior.listenerCount('data') === 0 && prior.listenerCount('readable') === 0) {
+                // Nobody ever read the prior life's stream: keep this one flowing-and-dropping so
+                // an unobserved chatty child cannot stall on stderr backpressure. A consumer who
+                // WAS reading re-reads the getter — its fresh stream buffers until then.
+                this._stderrStream.resume();
+            }
+        }
+
         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 +157,37 @@ export class StdioClientTransport implements Transport {
                 windowsHide: process.platform === 'win32',
                 cwd: this._serverParams.cwd
             });
-
-            this._process.on('error', error => {
+            this._process = proc;
+            // Per-life event scope: Node defers a child's 'close' event until its
+            // stdio pipes close, so a dead predecessor's events can land after a
+            // close() -> start() restart. Each handler bails when a SUCCESSOR
+            // occupies the slot; an empty slot (mid-close()) still delivers — that
+            // is the ordinary teardown notification.
+            const usurped = () => this._process !== undefined && this._process !== proc;
+
+            proc.on('error', error => {
                 reject(error);
+                if (usurped()) return;
                 this.onerror?.(error);
             });
 
-            this._process.on('spawn', () => {
+            proc.on('spawn', () => {
                 resolve();
             });
 
-            this._process.on('close', _code => {
+            proc.on('close', _code => {
+                if (usurped()) return;
                 this._process = undefined;
                 this.onclose?.();
             });
 
-            this._process.stdin?.on('error', error => {
+            proc.stdin?.on('error', error => {
+                if (usurped()) return;
                 this.onerror?.(error);
             });
 
-            this._process.stdout?.on('data', chunk => {
+            proc.stdout?.on('data', chunk => {
+                if (usurped()) return;
                 try {
                     this._readBuffer.append(chunk);
                     this.processReadBuffer();
@@ -167,12 +197,13 @@ export class StdioClientTransport implements Transport {
                 }
             });
 
-            this._process.stdout?.on('error', error => {
+            proc.stdout?.on('error', error => {
+                if (usurped()) return;
                 this.onerror?.(error);
             });
 
-            if (this._stderrStream && this._process.stderr) {
-                this._process.stderr.pipe(this._stderrStream);
+            if (this._stderrStream && proc.stderr) {
+                proc.stderr.pipe(this._stderrStream);
             }
         });
     }
@@ -183,6 +214,11 @@ 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. A fresh stream whose
+     * predecessor WAS being read buffers until read: leaving it unread can eventually stall a
+     * chatty child on stderr backpressure, not merely lose output.
      */
     get stderr(): Stream | null {
         if (this._stderrStream) {
@@ -217,6 +253,8 @@ export class StdioClientTransport implements Transport {
     }
 
     async close(): Promise<void> {
+        // Close-provenance stamp (see CLOSED_BY_CALLER): a local close is never respawned.
+        (this as { [CLOSED_BY_CALLER]?: boolean })[CLOSED_BY_CALLER] = true;
         if (this._process) {
             const processToClose = this._process;
             this._process = undefined;
@@ -252,8 +290,21 @@ export class StdioClientTransport implements Transport {
                     // ignore
                 }
             }
+
+            // Teardown is done: a predecessor whose stderr pipe outlives close()
+            // (a held-open pipe, a SIGKILL still landing) must not end the stream
+            // a NEXT life pipes into after start()'s recreation check. Detached
+            // here — not at the top — so shutdown-time stderr (the child's own
+            // signal/EOF diagnostics) still reaches subscribers during the waits above.
+            processToClose.stderr?.unpipe();
         }
 
+        // End the aggregate deterministically (idempotent; also for a transport
+        // that was never started): after the unpipe above the predecessor's own
+        // end can no longer arrive, so without this a stream whose child
+        // outlived close() would NEVER end — hanging finished()/for-await
+        // readers. start() begins the next life on a fresh stream.
+        this._stderrStream?.end();
         this._readBuffer.clear();
     }