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

A connection that closed while the server/discover probe awaited its
reply was a hard, untyped negotiation failure with no fallback. Stdio
servers built on SDKs that terminate on any pre-initialize request
(the official Rust SDK, rmcp, is the prominent example) connect fine
under mode 'legacy' but hard-failed under 'auto'.

- stdio: a server-side close during the probe is now a legacy signal,
  symmetric with the stdio probe-timeout rule. The stream died with the
  process, so the probe window leaves the transport's start() live and
  the Protocol.connect() handover restarts it (StdioClientTransport
  respawns from its retained parameters); the plain initialize fallback
  runs on the respawned process, byte-identical to a legacy connect.
- HTTP-class: a mid-probe close stays an error (never era evidence) but
  is now typed: SdkErrorCode.EraProbeConnectionClosed, a stable caller
  predicate instead of message-sniffing.
- A close initiated on the local side (transport.close() during the
  probe, caller shutdown or transport error recovery) gets the typed
  error on every transport: a local close never restarts the server.
  The probe window restores transport.close by identity, so repeated
  connects never stack wrapper layers.
- A restart that itself fails (respawn error, or a stdio-shaped custom
  transport whose start() cannot run again) rejects with a typed
  EraNegotiationFailed carrying the underlying error as data.cause.
- StdioClientTransport clears its read buffer on child exit so a
  restarted transport starts with a clean stream; with stderr 'pipe'
  the shared stderr stream is piped with end: false so it spans
  restarts (a respawned child's write to the ended stream raised an
  unhandled stream error) and carries every child's output; a stale
  child close event (close() can resolve before it fires) no longer
  clears a restarted transport's successor state.
- Pin-mode and modern-only failures name the mid-probe close instead of
  implying the server answered the probe.
- Migration docs: SdkErrorCode table gains the new code; the 2026
  probe-policy section documents the transport-aware close split.

Author: felixweinberger

.changeset/probe-close-handling.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+---
+
+Handle a connection that closes during the `server/discover` version-negotiation probe instead of dead-ending in an untyped failure.
+
+On stdio, a server process that exits on the unrecognized probe is now classified as a legacy signal — symmetric with the stdio probe-timeout rule. Stdio servers built on SDKs that terminate on any pre-`initialize` request (the official Rust SDK, rmcp, is the prominent example) previously connected fine under `mode: 'legacy'` but hard-failed under `mode: 'auto'`; the client now restarts the transport (`StdioClientTransport.start()` respawns the server from its retained parameters, exactly what a `mode: 'legacy'` connect would have done) and completes the plain `initialize` handshake there. The respawned process sees bytes identical to a plain legacy connect.
+
+On HTTP-class transports a mid-probe close stays an error — an ambiguous network condition is never era evidence — but is now typed: `SdkError` with the new `SdkErrorCode.EraProbeConnectionClosed`, giving callers a stable predicate instead of message-sniffing the previous generic `EraNegotiationFailed` wrapper. A close initiated on the local side (`transport.close()` during the probe — a caller shutdown, or the transport's own error recovery) gets the same typed error on every transport: a local close never restarts the server. A restart that itself fails (respawn error, or a stdio-shaped custom transport whose `start()` cannot run again) rejects with a typed `EraNegotiationFailed` carrying the underlying error as `data.cause`.
+
+`StdioClientTransport` also clears its read buffer when the child process exits, so a restarted transport never sees a trailing partial line from the dead process. With `stderr: 'pipe'`, the `stderr` stream now spans restarts: it is no longer ended by a child's exit, so it carries every child's output — key teardown on `onclose`, not on the stderr stream ending.

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

@@ -78,9 +78,17 @@ error. Probe timeouts are **transport-aware**: on **stdio** a server that does n
 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`
 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.
+a dead HTTP server is never misreported as legacy. A mid-probe **connection close** is
+transport-aware the same way: on **stdio** a server process that exits on the
+unrecognized probe is treated as legacy — the client restarts the transport (respawning
+the server) and falls back to `initialize` there (stdio servers built on SDKs that
+terminate on any pre-`initialize` request behave this way); on **HTTP** a mid-probe
+close rejects with `SdkError(EraProbeConnectionClosed)` — an ambiguous drop is never
+misreported as legacy. A close initiated locally via `transport.close()` during the
+probe rejects with the same typed error on every transport. 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.
 
 ```typescript
 versionNegotiation: {

docs/migration/upgrade-to-v2.md

@@ -996,6 +996,7 @@ the third argument — `new SdkHttpError(SdkErrorCode.ClientHttpNotImplemented,
 | `ListPaginationExceeded`              | No-arg `list*()` aggregate walk hit `listMaxPages`                         |
 | `MethodNotSupportedByProtocolVersion` | Outbound spec method does not exist on the negotiated protocol version     |
 | `EraNegotiationFailed`                | `connect()` could not negotiate a protocol era (probe failed / no overlap) |
+| `EraProbeConnectionClosed`            | Connection closed during the `server/discover` probe (HTTP-class transport, or a locally initiated close on any transport) |
 | `ClientHttpNotImplemented`            | HTTP POST request failed                                                   |
 | `ClientHttpAuthentication`            | Server returned 401 after re-authentication                                |
 | `ClientHttpForbidden`                 | Server returned 403 `insufficient_scope` after step-up retry cap           |

docs/protocol-versions.md

@@ -95,6 +95,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 server process that exits on the unrecognized probe is a legacy server — stdio servers built on SDKs that terminate on any pre-`initialize` request behave exactly this way (the official Rust SDK, rmcp, is the prominent example) — so `connect()` restarts the transport, respawning the server, and falls back to `initialize` there; the respawned process sees the same bytes a `mode: 'legacy'` connect would have sent. On HTTP a mid-probe close is ambiguous — a proxy drop or a crash, never era evidence — so `connect()` rejects with the typed `SdkError(EraProbeConnectionClosed)`.
+
 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

packages/client/src/client/client.ts

@@ -1077,11 +1077,35 @@ export class Client extends Protocol<ClientContext> {
             throw error;
         }
 
-        await super.connect(transport);
+        const restart = result.era === 'legacy' && result.restart === true;
+        try {
+            // On the stdio close-fallback (`restart`), negotiateEra left the
+            // transport's start() live, so this connect's unconditional start()
+            // genuinely restarts it — respawning the server process, exactly
+            // what a plain legacy connect does. Everywhere else start() is the
+            // armed one-shot pass-through.
+            await super.connect(transport);
+        } catch (error) {
+            if (!restart) throw error;
+            // A failed restart is a negotiation-phase failure: surface it with
+            // the typed contract every other negotiation failure has (the
+            // pre-restart behavior for a mid-probe close), not a raw transport
+            // error — e.g. a respawn spawn failure, or a stdio-shaped custom
+            // transport whose start() cannot run again after close.
+            await transport.close().catch(() => {});
+            throw new SdkError(
+                SdkErrorCode.EraNegotiationFailed,
+                'Version negotiation failed: the transport could not be restarted for the legacy fallback after the ' +
+                    `connection closed during the probe: ${error instanceof Error ? error.message : String(error)}`,
+                { cause: error }
+            );
+        }
 
         if (result.era === 'legacy') {
             // Conservative fallback: the plain legacy handshake on the SAME
-            // connection (the probe never touched the transport version slot).
+            // connection (the probe never touched the transport version slot) —
+            // or, on the stdio close-fallback, on the transport just restarted
+            // above (see the probe classifier's closed row for the rationale).
             await this._legacyHandshake(transport, options);
             return;
         }

packages/client/src/client/probeClassifier.ts

@@ -2,7 +2,8 @@
  * Probe outcome classifier (pure module): maps the outcome of the connect-time
  * `server/discover` probe onto one of four verdicts — modern era, the
  * spec-mandated `-32022` corrective continuation, legacy fallback (the plain
- * 2025 `initialize` handshake on the same connection), or a typed connect error.
+ * 2025 `initialize` handshake — on the same connection, or on a restarted
+ * transport when a stdio close consumed it), or a typed connect error.
  *
  * The classifier is deliberately conservative: anything it does not positively
  * recognize as modern resolves to the legacy fallback, and a network outage is a
@@ -48,6 +49,14 @@ 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.
+     * `localClose` is true when the close was initiated on the local side —
+     * `transport.close()` ran during the probe window, whether from a caller
+     * shutdown/abort or the transport's own error recovery — and is therefore
+     * never a server-side signal.
+     */
+    | { kind: 'closed'; localClose?: boolean }
     /** No response arrived within the probe timeout. */
     | { kind: 'timeout'; timeoutMs: number };
 
@@ -82,8 +91,15 @@ export type ProbeVerdict =
      * arms a loop guard on the second rejection, throwing `error`.
      */
     | { kind: 'corrective'; version: string; error: UnsupportedProtocolVersionError }
-    /** Definitive legacy signal or unrecognized shape: perform the plain legacy `initialize` handshake on the same connection. */
-    | { kind: 'legacy' }
+    /**
+     * Definitive legacy signal or unrecognized shape: perform the plain legacy
+     * `initialize` handshake on the same connection. `restart` marks the one
+     * row where the same connection no longer exists (stdio close): the
+     * handshake runs on a restarted transport instead — for the stdio
+     * transport, `start()` respawns the server process, which is exactly what
+     * a `mode: 'legacy'` connect would have done.
+     */
+    | { kind: 'legacy'; restart?: true }
     /** Typed connect error — never converted to an era verdict. */
     | { kind: 'error'; error: Error };
 
@@ -125,6 +141,39 @@ export function classifyProbeOutcome(outcome: ProbeOutcome, context: ProbeClassi
             // handshake an auth-gated modern server as legacy.
             return { kind: 'error', error: outcome.error };
         }
+        case 'closed': {
+            if (outcome.localClose) {
+                // The local side closed the transport mid-probe — a caller
+                // shutdown/abort, or the transport's own error recovery (e.g.
+                // read-buffer overflow). Never era evidence on any transport,
+                // and on stdio it must not respawn a process the local side
+                // chose to terminate.
+                return {
+                    kind: 'error',
+                    error: new SdkError(
+                        SdkErrorCode.EraProbeConnectionClosed,
+                        'Connection closed locally during the version negotiation probe'
+                    )
+                };
+            }
+            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). The
+                // stream died with the process, so the fallback cannot run on
+                // the same connection: `restart` has the caller run `initialize`
+                // on a restarted transport.
+                return { kind: 'legacy', restart: true };
+            }
+            // On HTTP a mid-probe close is an ambiguous network condition
+            // (proxy drop, crash, redeploy) — a typed connect error, never an
+            // era verdict.
+            return {
+                kind: 'error',
+                error: new SdkError(SdkErrorCode.EraProbeConnectionClosed, 'Connection closed during the version negotiation probe')
+            };
+        }
         case 'timeout': {
             if (context.transportKind === 'stdio') {
                 // Per the stdio transport's backward-compatibility rule, a probe

packages/client/src/client/stdio.ts

@@ -118,6 +118,14 @@ export class StdioClientTransport implements Transport {
 
     /**
      * Starts the server process and prepares to communicate with it.
+     *
+     * After the child process exits (`onclose`), `start()` may be called
+     * again: a fresh process is spawned from the same
+     * {@linkcode StdioServerParameters}. The client's version-negotiation
+     * close-fallback relies on this to run the legacy handshake after a
+     * server exits on the connect-time probe. With `stderr: 'pipe'`, the
+     * {@linkcode stderr} stream spans restarts — it is not ended by a
+     * child's exit and carries every child's output.
      */
     async start(): Promise<void> {
         if (this._process) {
@@ -127,7 +135,7 @@ export class StdioClientTransport implements Transport {
         }
 
         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 +146,35 @@ export class StdioClientTransport implements Transport {
                 windowsHide: process.platform === 'win32',
                 cwd: this._serverParams.cwd
             });
+            this._process = proc;
 
-            this._process.on('error', error => {
+            proc.on('error', error => {
                 reject(error);
                 this.onerror?.(error);
             });
 
-            this._process.on('spawn', () => {
+            proc.on('spawn', () => {
                 resolve();
             });
 
-            this._process.on('close', _code => {
+            proc.on('close', _code => {
+                // Stale-event guard: close() can resolve before this event
+                // fires, so a restarted transport may already own a successor
+                // child — its state must not be touched by the old child's exit.
+                if (this._process !== proc && this._process !== undefined) {
+                    return;
+                }
                 this._process = undefined;
+                // Drop any partial trailing line so a restarted transport starts with a clean stream.
+                this._readBuffer.clear();
                 this.onclose?.();
             });
 
-            this._process.stdin?.on('error', error => {
+            proc.stdin?.on('error', error => {
                 this.onerror?.(error);
             });
 
-            this._process.stdout?.on('data', chunk => {
+            proc.stdout?.on('data', chunk => {
                 try {
                     this._readBuffer.append(chunk);
                     this.processReadBuffer();
@@ -167,12 +184,15 @@ export class StdioClientTransport implements Transport {
                 }
             });
 
-            this._process.stdout?.on('error', error => {
+            proc.stdout?.on('error', error => {
                 this.onerror?.(error);
             });
 
-            if (this._stderrStream && this._process.stderr) {
-                this._process.stderr.pipe(this._stderrStream);
+            if (this._stderrStream && proc.stderr) {
+                // end: false — the shared PassThrough must survive a child exit
+                // so a restarted transport can pipe the next child's stderr into
+                // it (writing to an ended stream raises ERR_STREAM_WRITE_AFTER_END).
+                proc.stderr.pipe(this._stderrStream, { end: false });
             }
         });
     }
@@ -182,7 +202,8 @@ 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.
+     * error output emitted by the child process. The stream is not ended by a child's exit —
+     * it spans transport restarts; key teardown on `onclose` instead.
      */
     get stderr(): Stream | null {
         if (this._stderrStream) {