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

Author: felixweinberger

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

@@ -0,0 +1,11 @@
+---
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/core-internal': patch
+---
+
+Restores two v1 transport lifecycle invariants dropped in the v2 rewrite:
+
+- 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()` rejects 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

@@ -1576,6 +1576,43 @@ 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)
+
+Two 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."` — matching v1 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** (`"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.
+
+- **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()` resolves as a no-op and `ctx.mcpReq.send()` rejects 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

@@ -89,6 +89,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,17 @@ export class Client extends Protocol<ClientContext> {
      * ```
      */
     override async connect(transport: Transport, options?: ConnectOptions): Promise<void> {
+        // Fail fast while still connected: the negotiated paths below reset
+        // per-connection state and run the discover probe BEFORE the base
+        // Protocol.connect() reuse guard would fire — without this early
+        // check, a connect() on a connected instance would corrupt the live
+        // connection's state before throwing. Same guard + message as
+        // Protocol.connect().
+        if (this.transport) {
+            throw new Error(
+                'Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.'
+            );
+        }
         if (options?.prior !== undefined) {
             // Zero-round-trip reconnect from a previously-obtained
             // DiscoverResult: bypasses versionNegotiation resolution entirely.

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/core-internal/src/shared/protocol.ts

@@ -780,6 +780,12 @@ export abstract class Protocol<ContextT extends BaseContext> {
      * The caller assumes ownership of the {@linkcode Transport}, replacing any callbacks that have already been set, and expects that it is the only user of the {@linkcode Transport} instance going forward.
      */
     async connect(transport: Transport): Promise<void> {
+        if (this._transport) {
+            throw new Error(
+                'Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.'
+            );
+        }
+
         this._transport = transport;
         const _onclose = this.transport?.onclose;
         this._transport.onclose = () => {
@@ -813,7 +819,16 @@ export abstract class Protocol<ContextT extends BaseContext> {
         // Pass supported protocol versions to transport for header validation
         transport.setSupportedProtocolVersions?.(this._supportedProtocolVersions);
 
-        await this._transport.start();
+        try {
+            await this._transport.start();
+        } catch (error) {
+            // A transport that failed to start was never connected: unwind so
+            // the instance can retry connect() — the reuse guard above would
+            // otherwise lock the instance onto a transport that never carried
+            // traffic.
+            this._transport = undefined;
+            throw error;
+        }
     }
 
     /**
@@ -1024,22 +1039,41 @@ export abstract class Protocol<ContextT extends BaseContext> {
             return;
         }
 
+        const abortController = new AbortController();
+        this._requestHandlerAbortControllers.set(request.id, abortController);
+
         // Related sends resolve through the SAME instance era as every other
         // sender (the per-request/instance asymmetry is deliberately gone):
         // the codec is resolved at send time from the connection state.
-        const sendNotification = (notification: Notification, options?: NotificationOptions) =>
-            this._notificationViaCodec(this._resolveOutboundCodec(notification.method), notification, {
+        //
+        // Once this request's handler has been aborted (connection closed or
+        // request cancelled), its related sends must not reach the transport:
+        // `this._transport` is read live at send time, so a handler still
+        // running after close() could otherwise write onto a transport
+        // connected later. Notifications no-op; requests reject with
+        // ConnectionClosed.
+        const sendNotification = (notification: Notification, options?: NotificationOptions): Promise<void> => {
+            if (abortController.signal.aborted) {
+                return Promise.resolve();
+            }
+            return this._notificationViaCodec(this._resolveOutboundCodec(notification.method), notification, {
                 ...options,
                 relatedRequestId: request.id
             });
-        const sendRequest = <U extends StandardSchemaV1>(r: Request, resultSchema: U, options?: RequestOptions) =>
-            this._requestWithSchemaViaCodec(this._resolveOutboundCodec(r.method), r, resultSchema, {
+        };
+        const sendRequest = <U extends StandardSchemaV1>(
+            r: Request,
+            resultSchema: U,
+            options?: RequestOptions
+        ): Promise<StandardSchemaV1.InferOutput<U>> => {
+            if (abortController.signal.aborted) {
+                return Promise.reject(new SdkError(SdkErrorCode.ConnectionClosed, 'Request was cancelled'));
+            }
+            return this._requestWithSchemaViaCodec(this._resolveOutboundCodec(r.method), r, resultSchema, {
                 ...options,
                 relatedRequestId: request.id
             });
-
-        const abortController = new AbortController();
-        this._requestHandlerAbortControllers.set(request.id, abortController);
+        };
 
         // Multi-round-trip retry material: only BARE response objects are
         // surfaced to the handler; entries that look like a wrapped
@@ -1071,6 +1105,14 @@ export abstract class Protocol<ContextT extends BaseContext> {
                 // that overloaded property type. The cast is sound: this impl dispatches both overload paths via the
                 // isStandardSchema guard, and sendRequest validates the result against the resolved schema either way.
                 send: ((r: Request, schemaOrOptions?: StandardSchemaV1 | RequestOptions, maybeOptions?: RequestOptions) => {
+                    // The abort guard comes FIRST — before era/codec
+                    // resolution — so an aborted handler always gets the
+                    // documented ConnectionClosed rejection, never a
+                    // synchronous era throw evaluated against whatever
+                    // connection replaced this request's.
+                    if (abortController.signal.aborted) {
+                        return Promise.reject(new SdkError(SdkErrorCode.ConnectionClosed, 'Request was cancelled'));
+                    }
                     // Related requests resolve through the instance era at
                     // send time, exactly like direct sends: era-gate first,
                     // then method-keyed schema resolution.