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

@@ -83,6 +83,18 @@ 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.
 
+On the SDK's own stdio transport 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

@@ -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 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
@@ -1112,17 +1120,31 @@ 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;
         }
 

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

packages/client/src/client/stdio.ts

@@ -216,6 +216,44 @@ 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) {
+            this._readBuffer.clear();
+            return;
+        }
+        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;
+        this._readBuffer.clear();
+    }
+
     async close(): Promise<void> {
         if (this._process) {
             const processToClose = this._process;