review: type the lifecycle guard errors (SdkErrorCode.AlreadyConnected, new SdkErrorCode.StatelessTransportReuse) instead of raw Error

Author: felixweinberger

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

@@ -1,10 +1,10 @@
 ---
 '@modelcontextprotocol/server': patch
-'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/core-internal': minor
 '@modelcontextprotocol/client': patch
 ---
 
-Restores two v1 transport lifecycle invariants dropped in the v2 rewrite:
+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()` rejects with `SdkError(ConnectionClosed)`, consistent with the above.

docs/migration/upgrade-to-v2.md

@@ -64,8 +64,8 @@ The codemod ([`@modelcontextprotocol/codemod`](https://github.com/modelcontextpr
 mechanically applies every rename whose mapping is fixed. The mappings are the
 **source of truth** — they live in the codemod package and are not reproduced here:
 
-| Mapping                                                                                   | Source file                                                                                                       |
-| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Mapping                                                                                   | Source file                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@modelcontextprotocol/sdk/...` import paths → v2 packages                                | [`mappings/importMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts)                   |
 | Symbol renames (`McpError` → `ProtocolError`, `JSONRPCError` → `JSONRPCErrorResponse`, …) | [`mappings/symbolMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/symbolMap.ts)                   |
 | `setRequestHandler(Schema, …)` → `setRequestHandler('method/string', …)`                  | [`mappings/schemaToMethodMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/schemaToMethodMap.ts)   |
@@ -1583,28 +1583,30 @@ The following v1 transport lifecycle invariants (in effect since sdk@1.26.0) app
 - **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
+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** (`"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`.
+    ```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.
 

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

@@ -12,6 +12,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',
 

packages/core-internal/src/shared/protocol.ts

@@ -782,7 +782,8 @@ export abstract class Protocol<ContextT extends BaseContext> {
      */
     protected assertNotConnected(): void {
         if (this._transport) {
-            throw new Error(
+            throw new SdkError(
+                SdkErrorCode.AlreadyConnected,
                 'Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.'
             );
         }

packages/core-internal/test/shared/protocolConnectGuard.test.ts

@@ -94,7 +94,13 @@ describe('Protocol.connect() reuse guard', () => {
 
         await protocol.connect(transportA);
 
-        await expect(protocol.connect(transportB)).rejects.toThrow(
+        const rejection = await protocol.connect(transportB).then(
+            () => undefined,
+            (error: unknown) => error
+        );
+        expect(rejection).toBeInstanceOf(SdkError);
+        expect((rejection as SdkError).code).toBe(SdkErrorCode.AlreadyConnected);
+        expect((rejection as SdkError).message).toBe(
             'Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.'
         );
 

packages/core-internal/test/types/errorSurfacePins.test.ts

@@ -69,6 +69,7 @@ describe('SdkErrorCode', () => {
         expect({ ...SdkErrorCode }).toEqual({
             NotConnected: 'NOT_CONNECTED',
             AlreadyConnected: 'ALREADY_CONNECTED',
+            StatelessTransportReuse: 'STATELESS_TRANSPORT_REUSE',
             NotInitialized: 'NOT_INITIALIZED',
             CapabilityNotSupported: 'CAPABILITY_NOT_SUPPORTED',
             RequestTimeout: 'REQUEST_TIMEOUT',

packages/middleware/node/src/streamableHttp.ts

@@ -18,7 +18,7 @@ import type {
     Transport,
     WebStandardStreamableHTTPServerTransportOptions
 } from '@modelcontextprotocol/server';
-import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { SdkErrorCode, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
 
 /**
  * Configuration options for {@linkcode NodeStreamableHTTPServerTransport}
@@ -228,8 +228,10 @@ export class NodeStreamableHTTPServerTransport implements Transport {
         // throw. Re-raise it so the documented behavior (reusing a stateless
         // transport across requests throws at the call site) holds for the
         // Node adapter too. Other dispatch errors keep the existing
-        // 500-response behavior.
-        if (dispatchError instanceof Error && dispatchError.message.includes('Stateless transport cannot be reused across requests')) {
+        // 500-response behavior. Matched by code, not `instanceof`, so the
+        // check also holds if bundling ever yields two copies of the error
+        // class.
+        if (dispatchError instanceof Error && (dispatchError as { code?: unknown }).code === SdkErrorCode.StatelessTransportReuse) {
             throw dispatchError;
         }
     }

packages/middleware/node/test/streamableHttp.test.ts

@@ -1685,6 +1685,7 @@ describe('Zod v4', () => {
                 await sendPostRequest(sharedUrl, TEST_MESSAGES.toolsList);
                 expect(callSiteErrors).toHaveLength(1);
                 expect(callSiteErrors[0]!.message).toContain('Stateless transport cannot be reused across requests');
+                expect((callSiteErrors[0] as { code?: unknown }).code).toBe('STATELESS_TRANSPORT_REUSE');
             } finally {
                 sharedServer.close();
             }

packages/server/src/server/streamableHttp.ts

@@ -15,6 +15,8 @@ import {
     isJSONRPCRequest,
     isJSONRPCResultResponse,
     JSONRPCMessageSchema,
+    SdkError,
+    SdkErrorCode,
     SUPPORTED_PROTOCOL_VERSIONS
 } from '@modelcontextprotocol/core-internal';
 
@@ -376,7 +378,10 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         // In stateless mode (no sessionIdGenerator), each request must use a fresh transport.
         // Reusing a stateless transport causes message ID collisions between clients.
         if (!this.sessionIdGenerator && this._hasHandledRequest) {
-            throw new Error('Stateless transport cannot be reused across requests. Create a new transport per request.');
+            throw new SdkError(
+                SdkErrorCode.StatelessTransportReuse,
+                'Stateless transport cannot be reused across requests. Create a new transport per request.'
+            );
         }
         this._hasHandledRequest = true;
 

packages/server/test/server/statelessReuseGuard.test.ts

@@ -10,6 +10,7 @@
 import { randomUUID } from 'node:crypto';
 
 import type { CallToolResult, JSONRPCMessage } from '@modelcontextprotocol/core-internal';
+import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal';
 import { afterEach, describe, expect, it } from 'vitest';
 import * as z from 'zod/v4';
 
@@ -88,7 +89,13 @@ describe('stateless transport reuse guard', () => {
         const first = await transport.handleRequest(postRequest(initializeMessage));
         expect(first.status).toBe(200);
 
-        await expect(transport.handleRequest(postRequest(toolsListMessage))).rejects.toThrow(REUSE_ERROR);
+        const rejection = await transport.handleRequest(postRequest(toolsListMessage)).then(
+            () => undefined,
+            (error: unknown) => error
+        );
+        expect(rejection).toBeInstanceOf(SdkError);
+        expect((rejection as SdkError).code).toBe(SdkErrorCode.StatelessTransportReuse);
+        expect((rejection as SdkError).message).toMatch(REUSE_ERROR);
     });
 
     it('throws on a GET after a handled request', async () => {