fix(server): restore v1 transport lifecycle parity: single-use stateless transports, fail-fast on double connect

.changeset/stateless-transport-reuse-guard.md

@@ -0,0 +1,13 @@
+---
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/core-internal': minor
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/node': patch
+---
+
+Restores two v1 transport lifecycle invariants dropped in the v2 rewrite. Both throw typed errors — `SdkError` with `SdkErrorCode.StatelessTransportReuse` (new) and `SdkErrorCode.AlreadyConnected` — while keeping the message strings byte-identical to v1.x, so structured handling can use the code and existing message matching keeps working:
+
+- A stateless `WebStandardStreamableHTTPServerTransport` (`sessionIdGenerator: undefined`) handles a single request exchange and throws on reuse (matching v1 behavior since 1.26.0): `"Stateless transport cannot be reused across requests. Create a new transport per request."` Construct a fresh transport (and server instance) per request, or use `createMcpHandler`, which already serves per-request pairs. Stateful transports (`sessionIdGenerator` set) are unaffected; `NodeStreamableHTTPServerTransport` inherits the behavior.
+- `Protocol.connect()` (and `Client.connect()`) throw when the instance is already connected, instead of silently rebinding the transport: `"Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection."` Sequential `close()` then `connect()` keeps working. After `close()` aborts an in-flight request handler, `ctx.mcpReq.notify()` resolves as a no-op and `ctx.mcpReq.send()`, `ctx.mcpReq.elicitInput()`, and `ctx.mcpReq.requestSampling()` reject with `SdkError(ConnectionClosed)`, consistent with the above.
+
+Docs, middleware READMEs, and examples that showed a shared stateless transport now show the per-request pattern.

docs/migration/upgrade-to-v2.md

@@ -986,6 +986,7 @@ the third argument — `new SdkHttpError(SdkErrorCode.ClientHttpNotImplemented,
 | ------------------------------------- | -------------------------------------------------------------------------- |
 | `NotConnected`                        | Transport is not connected                                                 |
 | `AlreadyConnected`                    | Transport is already connected                                             |
+| `StatelessTransportReuse`             | Stateless transport reused across requests                                |
 | `NotInitialized`                      | Protocol is not initialized                                                |
 | `CapabilityNotSupported`              | Required capability is not supported                                       |
 | `RequestTimeout`                      | Request timed out waiting for response                                     |
@@ -1616,6 +1617,56 @@ rewrite required unless noted.
   unchanged from v1. This `-32001` is an SDK convention, not spec-assigned; client code
   should key off the HTTP `404` status, not `-32001`.
 
+#### Transport / connection lifecycle (v1 parity)
+
+The following v1 transport lifecycle invariants (in effect since sdk@1.26.0) apply in v2:
+
+- **A stateless `WebStandardStreamableHTTPServerTransport` serves exactly one request.**
+  With `sessionIdGenerator: undefined`, the second `handleRequest()` call throws
+  `"Stateless transport cannot be reused across requests. Create a new transport per
+request."` (an `SdkError` with code `StatelessTransportReuse`) — matching v1
+  message behavior since 1.26.0. Stateful transports
+  (`sessionIdGenerator` set) accept multiple requests as before;
+  `NodeStreamableHTTPServerTransport` inherits the behavior. Migrate shared-transport
+  hosting to the per-request pattern:
+
+    ```typescript
+    app.all('/mcp', async c => {
+        // Fresh transport + server pair per request.
+        const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        await server.connect(transport);
+        return transport.handleRequest(c.req.raw);
+    });
+    ```
+
+    Or use `createMcpHandler`, which constructs the per-request pair for you (its
+    `legacy: 'stateless'` fallback and the modern per-request transport are both
+    one-exchange by construction).
+
+- **`Protocol.connect()` throws when already connected** (an `SdkError` with code
+  `AlreadyConnected`: `"Already connected to a transport. Call close() before connecting
+to a new transport, or use a separate Protocol instance per connection."`) instead of
+  silently rebinding `this._transport`.
+  Sequential `close()` then `connect()` keeps working. `Client.connect()` performs the
+  same check up front, before any per-connection state is reset.
+  To resume a Streamable HTTP session across that sequence, carry both the session ID
+  and the negotiated protocol version onto the new transport — `close()` wipes the
+  client's copy, and the resuming connect reads it back from the transport:
+
+    ```typescript
+    const sessionId = transport.sessionId;
+    const protocolVersion = client.getNegotiatedProtocolVersion();
+    await client.close();
+    await client.connect(new StreamableHTTPClientTransport(url, { sessionId, protocolVersion }));
+    ```
+
+- **Aborted request handlers cannot write to a replacement transport.** After the
+  handler's `ctx.mcpReq.signal` aborts (connection closed or request cancelled),
+  `ctx.mcpReq.notify()` (and `ctx.mcpReq.log()`) resolves as a no-op, and
+  `ctx.mcpReq.send()`, `ctx.mcpReq.elicitInput()`, and `ctx.mcpReq.requestSampling()`
+  reject with `SdkError(ConnectionClosed)`.
+
 #### Server (deprecated accessors and app-factory Origin validation)
 
 - `Server.getClientCapabilities()`, `getClientVersion()`, `getNegotiatedProtocolVersion()`

docs/serving/sessions-state-scaling.md

@@ -7,7 +7,7 @@ shape: how-to
 
 ## Pin a client to a session
 
-A **session** pins a client to one long-lived transport instance; sessions belong to the hand-wired 2025-era transport — the 2026-07-28 revision is per-request and has no `Mcp-Session-Id` ([Protocol versions](../protocol-versions.md)). On `NodeStreamableHTTPServerTransport`, `sessionIdGenerator` turns sessions on; leaving it `undefined` is stateless mode.
+A **session** pins a client to one long-lived transport instance; sessions belong to the hand-wired 2025-era transport — the 2026-07-28 revision is per-request and has no `Mcp-Session-Id` ([Protocol versions](../protocol-versions.md)). On `NodeStreamableHTTPServerTransport`, `sessionIdGenerator` turns sessions on; leaving it `undefined` is stateless mode. A stateless transport serves exactly one request exchange; construct a fresh transport + server pair per request — reuse throws. For stateless HTTP hosting prefer `createMcpHandler`, which builds the per-request pair for you.
 
 ```ts source="../../examples/guides/serving/sessions-state-scaling.examples.ts#sessions_stateful"
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';

examples/README.md

@@ -92,6 +92,8 @@ To enable stateless mode, configure the `NodeStreamableHTTPServerTransport` with
 sessionIdGenerator: undefined;
 ```
 
+A stateless transport serves exactly one request: construct a fresh transport + server pair per request (reuse throws). `createMcpHandler` does this for you — see [`stateless-legacy/`](./stateless-legacy/README.md).
+
 ```
 ┌─────────────────────────────────────────────┐
 │                  Client                     │

packages/client/src/client/client.ts

@@ -927,6 +927,9 @@
      * ```
      */
     override async connect(transport: Transport, options?: ConnectOptions): Promise<void> {
+        // Guard before the paths below mutate per-connection state — the base
+        // Protocol.connect() check would fire only after that corruption.
+        this.assertNotConnected();
         if (options?.prior !== undefined) {
             // Zero-round-trip reconnect from a previously-obtained
             // DiscoverResult: bypasses versionNegotiation resolution entirely.
@@ -938,27 +941,20 @@
         }
         // Plain legacy connect — the pinned 2025 sequence, byte-untouched.
         await super.connect(transport);
-        // When transport sessionId is already set this means we are trying to reconnect.
-        // Restore the protocol version negotiated during the original initialize handshake
-        // so HTTP transports include the required mcp-protocol-version header, but skip re-init.
+        // Session resume (transport carries a sessionId): skip re-init, restore
+        // the originally negotiated version — from this instance, or from the
+        // transport itself after close() wiped the instance's copy.
         if (transport.sessionId !== undefined) {
-            const negotiatedProtocolVersion = this._negotiatedProtocolVersion;
-            if (negotiatedProtocolVersion !== undefined) {
-                // Resuming keeps the original negotiation: the instance still
-                // holds the negotiated version (and with it the wire era) —
-                // only the new transport needs the header pushed again.
-                transport.setProtocolVersion?.(negotiatedProtocolVersion);
+            const version = this._negotiatedProtocolVersion ?? transport.protocolVersion;
+            if (version !== undefined) {
+                this._negotiatedProtocolVersion = version;
+                transport.setProtocolVersion?.(version);
             }
             return;
         }
-        // Fresh connect: per-connection state left over from a previous
-        // connection must not survive into a new handshake. Clearing it puts
-        // the instance back in the pre-negotiation phase, so the initialize
-        // exchange below rides the bootstrap method pins (legacy era) instead
-        // of a dead session's era. Without this, an instance that once
-        // negotiated a modern era could never re-run a fresh handshake:
-        // `initialize` is physically absent from the modern registry. (The
-        // resume branch above keeps it instead.)
+        // Fresh connect: clear leftover connection state so `initialize` rides
+        // the legacy bootstrap pins — a stale modern era would make it
+        // unsendable (absent from the modern registry).
         this._resetConnectionState();
         await this._legacyHandshake(transport, options);
     }
@@ -1046,13 +1042,14 @@
         negotiation: Extract<ResolvedVersionNegotiation, { kind: 'auto' | 'pin' }>,
         options?: RequestOptions
     ): Promise<void> {
-        // Session-resuming reconnect: restore the previously negotiated version,
-        // never re-probe mid-session.
+        // Session resume: never re-probe; restore the negotiated version from
+        // this instance or, after close() wiped it, from the transport itself.
         if (transport.sessionId !== undefined) {
             await super.connect(transport);
-            const negotiatedProtocolVersion = this._negotiatedProtocolVersion;
-            if (negotiatedProtocolVersion !== undefined && transport.setProtocolVersion) {
-                transport.setProtocolVersion(negotiatedProtocolVersion);
+            const version = this._negotiatedProtocolVersion ?? transport.protocolVersion;
+            if (version !== undefined) {
+                this._negotiatedProtocolVersion = version;
+                transport.setProtocolVersion?.(version);
             }
             return;
         }

packages/client/test/client/listen.test.ts

@@ -837,26 +837,41 @@ describe('Client.listen()', () => {
         await client.close();
     });
 
-    it('a fresh connect without an intervening close settles in-flight listen() from the prior connection', async () => {
-        // Edge: prior transport never fires onclose; consumer calls connect()
-        // again. The in-flight listen() promise from the old connection must
-        // reject with a clear "client reconnected/closed" error rather than
-        // hang on the (now-discarded) ack timer.
+    it('connect() without an intervening close throws; close() settles in-flight listen() from the prior connection', async () => {
+        // Edge: prior transport never spontaneously fires onclose; consumer
+        // calls connect() again. The transport-reuse guard rejects the second
+        // connect outright WITHOUT touching the live connection's state (the
+        // in-flight listen stays pending), and the close() now required in
+        // between settles the in-flight listen() promise with a clear
+        // "client reconnected/closed" error rather than leaving it hanging on
+        // the (now-discarded) ack timer.
         const { clientTx } = await scriptedModernNoAck();
         const client = new Client({ name: 'c', version: '1' }, { versionNegotiation: { mode: 'auto' } });
         await client.connect(clientTx);
         const pending = client.listen({ toolsListChanged: true });
         await flush();
         expect((client as unknown as { _listenState: Map<unknown, unknown> })._listenState.size).toBe(1);
-        // Fresh connect on a new transport — _resetConnectionState runs.
+        // Fresh connect on a new transport without close() — rejected by the
+        // reuse guard, and the prior connection's listen state is untouched.
         const { clientTx: clientTx2 } = await scriptedModern();
-        await client.connect(clientTx2);
+        await expect(client.connect(clientTx2)).rejects.toThrow(
+            'Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.'
+        );
+        expect((client as unknown as { _listenState: Map<unknown, unknown> })._listenState.size).toBe(1);
+        // close() settles the in-flight listen even though the prior server
+        // never acked or closed.
+        await client.close();
         const error = await pending.catch(e => e as Error);
         expect(error).toBeInstanceOf(SdkError);
         expect((error as SdkError).code).toBe(SdkErrorCode.ConnectionClosed);
-        expect((error as SdkError).message).toContain('reconnected or closed');
+        // Settled via the transport onclose path ('Connection closed') or the
+        // reset path ('reconnected or closed') — both are clean
+        // ConnectionClosed settlements, never a hang.
+        expect((error as SdkError).message).toMatch(/Connection closed|reconnected or closed/);
         // No leaked per-listen state from the old connection.
         expect((client as unknown as { _listenState: Map<unknown, unknown> })._listenState.size).toBe(0);
+        // The instance is reusable after close(): a fresh connect succeeds.
+        await client.connect(clientTx2);
         await client.close();
     });
 

packages/client/test/client/versionNegotiation.test.ts

@@ -82,6 +82,7 @@ class ScriptedTransport implements Transport {
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
     sessionId?: string;
+    protocolVersion?: string;
 
     startCalls = 0;
     sent: JSONRPCMessage[] = [];
@@ -698,6 +699,23 @@ describe('era scope discipline', () => {
         await client.close();
     });
 
+    test('session resume on a fresh auto client adopts the transport-carried version: no probe, no initialize', async () => {
+        // After close() (or on a brand-new client) the instance holds no
+        // negotiated version — a resuming transport constructed with
+        // { sessionId, protocolVersion } supplies it instead.
+        const transport = new ScriptedTransport(() => {});
+        transport.sessionId = 'sess-1';
+        transport.protocolVersion = MODERN;
+        const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
+
+        await client.connect(transport);
+
+        expect(requests(transport.sent)).toHaveLength(0);
+        expect(transport.setProtocolVersionCalls).toEqual([MODERN]);
+        expect(client.getNegotiatedProtocolVersion()).toBe(MODERN);
+        await client.close();
+    });
+
     test('no era state exists before the first connect, and none is persisted anywhere', () => {
         const client = new Client({ name: 'c', version: '0' }, { versionNegotiation: { mode: 'auto' } });
         expect(client.getNegotiatedProtocolVersion()).toBeUndefined();

packages/core-internal/src/errors/sdkErrors.ts

@@ -14,6 +14,8 @@ export enum SdkErrorCode {
     NotConnected = 'NOT_CONNECTED',
     /** Transport is already connected */
     AlreadyConnected = 'ALREADY_CONNECTED',
+    /** A stateless (sessionless) transport was asked to handle a second request exchange */
+    StatelessTransportReuse = 'STATELESS_TRANSPORT_REUSE',
     /** Protocol is not initialized */
     NotInitialized = 'NOT_INITIALIZED',