fix(client): probe stdio servers on a disposable sibling process

Some stdio servers exit on any pre-initialize request, so the
server/discover version-negotiation probe killed the server and
connect() hard-failed under mode 'auto' while mode 'legacy' worked.
The probe now runs on a short-lived sibling spawned from the same
parameters (stderr discarded, reaped once the era is known — awaiting
process exit, never held-open pipes) and the caller's transport starts
exactly once, afterwards: a legacy verdict connects with the plain
initialize handshake, byte-identical to mode 'legacy'; a modern verdict
adopts the sibling's DiscoverResult directly, so the session wire never
carries server/discover. Closing the caller's transport during the
probe aborts promptly with the typed error and the session child is
never spawned. On HTTP, and on custom stdio-shaped transports (which
probe in place), a mid-probe close keeps rejecting with the typed
connect error, now naming the close in pin/modern-only diagnostics.

Author: felixweinberger

.changeset/probe-close-handling.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Probe stdio servers on a disposable sibling process. Some stdio servers exit on any pre-`initialize` request (servers built on the official Rust SDK, rmcp, behave this way), so under `versionNegotiation: { mode: 'auto' }` the `server/discover` probe previously killed the server and `connect()` hard-failed. The probe now runs on a short-lived sibling spawned from the same parameters — its stderr is discarded and it is reaped once the era is known — and the caller's transport spawns exactly once, afterwards: a legacy verdict connects with the plain `initialize` handshake (byte-identical to `mode: 'legacy'`), a modern verdict is adopted directly, and the session wire never carries `server/discover`. Closing the caller's transport during the probe aborts `connect()` with the typed `SdkError(EraNegotiationFailed)` and the session child is never spawned. On HTTP — and on custom stdio-shaped transports, which probe in place — a mid-probe connection close keeps rejecting with the typed connect error, now naming the close in pin-mode and modern-only diagnostics.

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

@@ -55,8 +55,9 @@ client.getProtocolEra(); // 'modern' | 'legacy'
 ```
 
 - **absent / `mode: 'legacy'`** (default) — today's behavior, no probe.
-- **`mode: 'auto'`** — probe with `server/discover`; fall back to the 2025 handshake on
-  the same connection against a 2025-only server (one extra round trip).
+- **`mode: 'auto'`** — probe with `server/discover`; fall back to the 2025 handshake
+  against a 2025-only server (one extra round trip; on the SDK's stdio transport the
+  probe rides a disposable sibling process — see below).
 - **`mode: { pin: '2026-07-28' }`** — modern only; no fallback, `connect()` rejects with
   `SdkError(EraNegotiationFailed)` against a 2025-only server.
 
@@ -77,12 +78,25 @@ falls back to the legacy era — provided the supported-versions list still cont
 `SdkError(EraNegotiationFailed)` instead. A network outage rejects with a typed connect
 error. Probe timeouts are **transport-aware**: on **stdio** a server that does not
 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`
+(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
 deployed 2025 servers commonly have CORS allow-lists that predate the 2026 headers.
 
+On the SDK's own stdio transport (exactly `StdioClientTransport` — subclasses probe
+in place, like custom stdio-shaped transports) the probe runs on a short-lived
+**sibling process** spawned from the same parameters (its stderr is discarded, and it is reaped once the
+era is known): some stdio servers exit on any pre-`initialize` request — servers built
+on the official Rust SDK, rmcp, behave this way — so the probe must not spend the
+caller's one child process. A child that exits on the probe is simply a legacy server;
+the caller's transport spawns exactly once, after the era is known, and its wire never
+carries `server/discover`. Closing the caller's transport during the probe aborts
+`connect()` with a typed `SdkError(EraNegotiationFailed)` and the session child is
+never spawned. On HTTP — and on custom stdio-shaped transports, which probe in
+place — a mid-probe connection close rejects with the same typed error as any probe
+transport failure.
+
 ```typescript
 versionNegotiation: {
     mode: 'auto',

docs/protocol-versions.md

@@ -30,7 +30,7 @@ console.log(client.getProtocolEra());
 modern
 ```
 
-Point the same options at a 2025-only server and `connect()` falls back to the `initialize` handshake on the same connection — one extra round trip, no error.
+Point the same options at a 2025-only server and `connect()` falls back to the `initialize` handshake — one extra round trip, no error (on the SDK's stdio transport the probe rides a disposable sibling process; see below).
 
 ```ts source="../examples/guides/protocolVersions.examples.ts#versionNegotiation_fallback"
 const fallback = new Client({ name: 'my-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
@@ -99,12 +99,14 @@ 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 probe timeout is transport-aware. On stdio a silent server is a legacy server, so `connect()` falls back to `initialize`; 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.
+
+On the SDK's own stdio transport (exactly `StdioClientTransport` — subclasses, like custom stdio-shaped transports, probe in place) the probe runs on a short-lived **sibling process** spawned from the same parameters — some stdio servers exit on any pre-`initialize` request (servers built on the official Rust SDK, rmcp, behave this way), so the probe must not spend the caller's one child process. The sibling is invisible infrastructure: its stderr is discarded and it is reaped once the era is known; the caller's transport spawns exactly once, afterwards, and its wire never carries `server/discover`. A child that exits on the probe is simply a legacy server (its exit must close the child's stdio pipes to register — an exit hidden behind a helper process holding them open falls to the probe-timeout path). Closing the caller's transport during the probe aborts `connect()` with a typed `SdkError(EraNegotiationFailed)` and the session child is never spawned. On HTTP — and on custom stdio-shaped transports, which probe in place — a mid-probe connection close rejects with the same typed error 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
-Do not default a spawn-per-invocation CLI tool to `'auto'`. On stdio, a legacy server that never answers unknown pre-`initialize` requests stalls `connect()` for the full probe timeout before falling back, and the extra round trip changes recorded transcripts. Keep the default and expose `'auto'` (or a pin) as a flag.
+Do not default a spawn-per-invocation CLI tool to `'auto'`. On stdio, a legacy server that never answers unknown pre-`initialize` requests stalls `connect()` for the full probe timeout before falling back, and the probe spawns an extra short-lived server process per connect. Keep the default and expose `'auto'` (or a pin) as a flag.
 :::
 
 ## Serve both eras from one entry point

packages/client/src/client/client.ts

@@ -84,7 +84,15 @@ import type { PriorDiscovery } from './probeClassifier';
 import type { CacheMode, CacheScope, ResponseCacheStore } from './responseCache';
 import { ClientResponseCache, InMemoryResponseCacheStore, MAX_CACHE_TTL_MS } from './responseCache';
 import type { ResolvedVersionNegotiation, VersionNegotiationOptions } from './versionNegotiation';
-import { detectProbeEnvironment, detectProbeTransportKind, negotiateEra, resolveVersionNegotiation } from './versionNegotiation';
+import {
+    detectProbeEnvironment,
+    detectProbeTransportKind,
+    disarmSpentCloseGuard,
+    negotiateEra,
+    negotiateStdioViaSibling,
+    readStdioServerParams,
+    resolveVersionNegotiation
+} from './versionNegotiation';
 
 /**
  * The server identity a `DiscoverResult` carries in
@@ -199,11 +207,15 @@ export type ClientOptions = ProtocolOptions & {
      * - `mode: 'auto'` — `connect()` probes the server with `server/discover` first:
      *   definitive modern evidence selects the modern era; definitive legacy signals
      *   (and anything unrecognized) fall back to the plain legacy `initialize`
-     *   handshake on the same connection, byte-equivalent to a 2025 client. A
+     *   handshake, byte-equivalent to a 2025 client. On the SDK's own stdio
+     *   transport the probe runs on a short-lived sibling process spawned from the
+     *   same parameters (one extra spawn per connect; its stderr is discarded) and
+     *   the caller's transport starts once, after the era is known; HTTP — and
+     *   custom stdio-shaped transports — probe on the connection itself. A
      *   network outage rejects with a typed connect error. A probe timeout is
      *   transport-aware: on stdio it indicates a legacy server (some legacy servers
      *   never answer unknown pre-`initialize` requests) and falls back to
-     *   `initialize` on the same stream; on HTTP it rejects with a typed timeout
+     *   `initialize`; on HTTP it rejects with a typed timeout
      *   error (silence on a deployed server is an outage, not a legacy signal).
      * - `mode: { pin: '2026-07-28' }` — modern era at exactly the pinned revision;
      *   no probe-and-fallback: anything else fails loudly.
@@ -1014,8 +1026,9 @@ export class Client extends Protocol<ClientContext> {
 
     /**
      * The 2025 `initialize` handshake — the body of the plain legacy connect and
-     * the `'auto'`-mode fallback path (same connection, same `initialize` body,
-     * zero 2026 headers). Callers clear the negotiated protocol version before
+     * the `'auto'`-mode fallback path (same `initialize` body, zero 2026 headers;
+     * on the stdio sibling path it opens the session child's fresh pipe, in the
+     * in-place modes it rides the probed connection). Callers clear the negotiated protocol version before
      * the handshake; its completion sets the negotiated (legacy) version.
      */
     private async _legacyHandshake(transport: Transport, options?: RequestOptions): Promise<void> {
@@ -1087,8 +1100,9 @@ export class Client extends Protocol<ClientContext> {
 
     /**
      * Negotiated connect (mode `'auto'` or `{ pin }`): probe with `server/discover`
-     * before the Protocol machinery attaches, then either establish the modern era
-     * or perform the plain legacy handshake on the same connection.
+     * before the Protocol machinery attaches — on a disposable sibling process for
+     * the SDK's stdio transport, in place otherwise — then either establish the
+     * modern era or perform the plain legacy handshake.
      */
     private async _connectNegotiated(
         transport: Transport,
@@ -1112,25 +1126,48 @@ export class Client extends Protocol<ClientContext> {
 
         let result: Awaited<ReturnType<typeof negotiateEra>>;
         try {
-            result = await negotiateEra(negotiation, {
-                transport,
+            const transportKind = detectProbeTransportKind(transport);
+            const baseDeps = {
                 clientInfo: this._clientInfo,
                 capabilities: this._capabilities,
                 environment: detectProbeEnvironment(),
-                transportKind: detectProbeTransportKind(transport),
                 defaultTimeoutMs: options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC
-            });
+            };
+            // The SDK's stdio transport probes on a disposable sibling process,
+            // so the caller's transport spends its one child life on the
+            // session, never on the probe. Stdio-shaped transports without
+            // readable spawn parameters (and HTTP) probe in place, as before.
+            const stdioParams = transportKind === 'stdio' ? readStdioServerParams(transport) : undefined;
+            result =
+                stdioParams === undefined
+                    ? await negotiateEra(negotiation, { ...baseDeps, transport, transportKind })
+                    : await negotiateStdioViaSibling(negotiation, transport, stdioParams, baseDeps);
         } catch (error) {
             // Typed connect error — close the channel like a failed initialize does.
             await transport.close().catch(() => {});
+            // The cleanup close has settled: any re-delivery of a spent
+            // mid-probe close has happened by now, so the spent-close guard
+            // must not outlive it — on transports whose close() never re-fires
+            // onclose (stdio), an armed guard would swallow the next GENUINE
+            // close after a restart.
+            disarmSpentCloseGuard(transport);
             throw error;
         }
 
+        // Success path: no cleanup close ever runs here, so no re-delivery of a
+        // spent mid-window close is coming — disarm any guard NOW, before
+        // Protocol chains the handler slot, or an in-place negotiation that
+        // succeeded after a same-tick reply-then-close would carry the armed
+        // skip into the live session and swallow its first genuine close.
+        disarmSpentCloseGuard(transport);
+
         await super.connect(transport);
 
         if (result.era === 'legacy') {
-            // Conservative fallback: the plain legacy handshake on the SAME
-            // connection (the probe never touched the transport version slot).
+            // Conservative fallback: the in-place probing modes run the plain
+            // legacy handshake on the probed connection; the sibling path runs
+            // it as the session child's first exchange (the probe never touched
+            // the transport version slot either way).
             await this._legacyHandshake(transport, options);
             return;
         }

packages/client/src/client/probeClassifier.ts

@@ -28,10 +28,11 @@ import {
 export type ProbeEnvironment = 'node' | 'browser';
 
 /**
- * The transport class the probe ran on. Only consulted for the timeout row: a
- * stdio probe that times out signals a legacy server, while an HTTP timeout
- * stays a typed error. Anything that is not the stdio child-process transport
- * is treated like HTTP.
+ * The transport class the probe ran on. Consulted for the timeout and closed
+ * rows: a stdio probe that times out — or whose child exits, closing the
+ * connection — signals a legacy server, while an HTTP timeout or close stays
+ * a typed error. Anything that is not the stdio child-process transport is
+ * treated like HTTP.
  */
 export type ProbeTransportKind = 'stdio' | 'http';
 
@@ -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 };
 
@@ -141,6 +144,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

packages/client/src/client/stdio.ts

@@ -216,6 +216,61 @@ export class StdioClientTransport implements Transport {
         }
     }
 
+    /**
+     * Reap a disposable probe sibling (see the version-negotiation sibling
+     * flow): signal-first teardown awaiting process `exit` — never the `close`
+     * event, so a helper process holding the child's stdio pipes can never
+     * block disposal. Not part of the public transport lifecycle.
+     *
+     * @internal
+     */
+    private async _dispose(): Promise<void> {
+        const proc = this._process;
+        this._process = undefined;
+        if (proc && proc.exitCode === null && proc.signalCode === null) {
+            const exited = new Promise<void>(resolve => proc.once('exit', () => resolve()));
+            try {
+                proc.stdin?.end();
+            } catch {
+                // ignore
+            }
+            try {
+                proc.kill('SIGTERM');
+            } catch {
+                // ignore
+            }
+            await Promise.race([exited, new Promise(resolve => setTimeout(resolve, 1000).unref())]);
+            if (proc.exitCode === null && proc.signalCode === null) {
+                try {
+                    proc.kill('SIGKILL');
+                } catch {
+                    // ignore
+                }
+            }
+            await exited;
+        }
+        // The child is gone — release the PARENT-side pipe handles too. A helper
+        // process holding the inherited write ends would otherwise keep them (and
+        // with them the host's event loop: stdout carries a flowing 'data'
+        // listener from start()) alive until the helper exits.
+        try {
+            proc?.stdout?.destroy();
+        } catch {
+            // ignore
+        }
+        try {
+            proc?.stdin?.destroy();
+        } catch {
+            // ignore
+        }
+        try {
+            proc?.stderr?.destroy();
+        } catch {
+            // ignore
+        }
+        this._readBuffer.clear();
+    }
+
     async close(): Promise<void> {
         if (this._process) {
             const processToClose = this._process;