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. The respawn is gated on a close-provenance
stamp (internal well-known symbol, implemented by StdioClientTransport):
a transport the caller closed mid-probe, or one that does not report
provenance, rejects with the typed connect error instead, and HTTP-class
mid-probe closes keep rejecting typed. StdioClientTransport.start()
clears the read buffer, and close() detaches the child's stderr pipe and
ends the aggregate stream once teardown completes, 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.

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 (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.start()` now also clears the read buffer, and `close()` detaches the child's stderr pipe and ends the aggregate stream once teardown completes, 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).

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

@@ -82,6 +82,12 @@ 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.
 
+One behavior change to the transport itself: 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.
+
 ```typescript
 versionNegotiation: {
     mode: 'auto',

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, 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/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 './versionNegotiation';
+
 export type StdioServerParameters = {
     /**
      * The executable to run to start the server.
@@ -126,6 +128,16 @@ 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.
+            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 +195,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 +232,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,6 +269,19 @@ 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();
+            // ...and end the aggregate deterministically: after the unpipe 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. A stream the graceful path already
+            // ended is unaffected; start() begins the next life on a fresh one.
+            this._stderrStream?.end();
         }
 
         this._readBuffer.clear();

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,16 @@ 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()`; only for transports that positively report close provenance,
+ *   as the SDK's `StdioClientTransport` does — others reject with the typed
+ *   connect error) and runs `initialize` on the fresh child. The exit counts
+ *   as a close only once it closes the child's stdio pipes; an exit hidden
+ *   behind a helper process holding them open falls to the probe-timeout
+ *   path instead. On HTTP a mid-probe close 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.
@@ -158,6 +167,22 @@ export function detectProbeTransportKind(transport: Transport): ProbeTransportKi
     return 'stderr' in transport && 'pid' in transport ? 'stdio' : 'http';
 }
 
+/**
+ * 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. Internal — not part of the public surface.
+ */
+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. */
+function closeProvenance(transport: Transport): boolean | undefined {
+    const value = (transport as { [CLOSED_BY_CALLER]?: unknown })[CLOSED_BY_CALLER];
+    return typeof value === 'boolean' ? value : undefined;
+}
+
 /** Raw reply from one probe exchange, before normalization. */
 type RawProbeReply =
     | { kind: 'response'; result?: unknown; error?: { code: number; message: string; data?: unknown } }
@@ -264,6 +289,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 +374,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 };
@@ -421,22 +458,72 @@ export async function negotiateEra(
                     continue;
                 }
                 case 'legacy': {
+                    // A closed outcome carries its own cause — the pin and
+                    // modern-only diagnostics must name the close (the caller's
+                    // own close when provenance says so) instead of implying a
+                    // server/discover verdict that never happened.
+                    const closedCause =
+                        outcome.kind === 'closed'
+                            ? closeProvenance(deps.transport) === true
+                                ? 'the transport was closed during the server/discover probe'
+                                : 'the connection closed during the server/discover probe'
+                            : undefined;
                     if (negotiation.kind === 'pin') {
                         throw new SdkError(
                             SdkErrorCode.EraNegotiationFailed,
-                            `Version negotiation failed: the server did not offer pinned protocol version ${negotiation.version} ` +
-                                `via server/discover (no fallback in pin mode)`
+                            closedCause === undefined
+                                ? `Version negotiation failed: the server did not offer pinned protocol version ${negotiation.version} ` +
+                                  `via server/discover (no fallback in pin mode)`
+                                : `Version negotiation failed: ${closedCause} before the server offered ` +
+                                  `pinned protocol version ${negotiation.version} (no fallback in pin mode)`
                         );
                     }
                     if (!negotiation.fallbackAvailable) {
                         // Modern-only client: the legacy initialize fallback is
                         // unavailable and must never carry a 2026-era version string.
                         throw new SdkError(
                             SdkErrorCode.EraNegotiationFailed,
-                            'Version negotiation failed: the server gave no modern evidence and this client supports no ' +
-                                'pre-2026-07-28 protocol version to fall back to'
+                            closedCause === undefined
+                                ? 'Version negotiation failed: the server gave no modern evidence and this client supports no ' +
+                                  'pre-2026-07-28 protocol version to fall back to'
+                                : `Version negotiation failed: ${closedCause} and this client supports no ` +
+                                  '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 —
+                        // but only on positive provenance that the close was
+                        // NOT local. The read happens BEFORE our own close()
+                        // below (the only close this path issues; start()
+                        // re-stamps false), so `true` always means the caller
+                        // closed mid-probe: never override that kill decision.
+                        // An absent stamp (custom/wrapper transports) fails
+                        // safe: never respawn a transport that cannot
+                        // distinguish its own close() from a child death.
+                        const provenance = closeProvenance(deps.transport);
+                        if (provenance !== false) {
+                            throw new SdkError(
+                                SdkErrorCode.EraNegotiationFailed,
+                                provenance === true
+                                    ? 'Version negotiation failed: the transport was closed during the server/discover probe'
+                                    : 'Version negotiation failed: the connection closed during the server/discover probe and ' +
+                                      'this transport does not report close provenance, so the legacy-fallback respawn is unavailable'
+                            );
+                        }
+                        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': {