Type inconsistency: StreamableHTTPServerTransport.onclose widens Transport interface contract under exactOptionalPropertyTypes

[swadel]

SDK version: 1.29.0. TypeScript version: 5.9.3. tsconfig flags: strict true, exactOptionalPropertyTypes true, noUncheckedIndexedAccess true, target ES2022, module NodeNext.

Problem: the Transport interface in shared/transport.d.ts declares onclose as optional with type () => void (no explicit | undefined). The concrete StreamableHTTPServerTransport class in server/streamableHttp.d.ts declares onclose via getter/setter typed (() => void) | undefined. Under exactOptionalPropertyTypes, these two declarations are incompatible: the concrete class widens the optional property to include undefined, but the interface contract does not. As a result, passing a StreamableHTTPServerTransport instance into McpServer.connect(transport: Transport) fails typecheck with TS2379.

Reproduction: create a TypeScript project with the flag set above, import StreamableHTTPServerTransport and McpServer, attempt server.connect(new StreamableHTTPServerTransport()).

Expected: typechecks cleanly because the SDK's own concrete transport class should be assignable to the SDK's own Transport interface.

Actual: TS2379 on the property variance.

Asymmetry note: the client-side StreamableHTTPClientTransport declares onclose with the narrower () => void shape and typechecks cleanly under EOPT. Only the server-side transport hits this.

Suggested fix: align StreamableHTTPServerTransport.onclose to () => void to match the Transport interface declaration, OR widen Transport.onclose explicitly to (() => void) | undefined. Either direction resolves the variance for EOPT consumers.

Workaround consumers must use today: targeted cast at the connect call site, e.g. server.connect(transport as Transport).

[jshaofa-ui]

💡 Proposed Solution

Root Cause

Under exactOptionalPropertyTypes: true, the server transport's _onclose field is typed as (() => void) | undefined, while the Transport interface declares onclose?: () => void. The | undefined widening causes TS2379 variance error.

Proposed Fix (Option A — Recommended)

In src/server/streamableHttp.ts, change the private field type:

// Before:
private _onclose?: (() => void) | undefined;

// After:
private _onclose?: () => void;

Alternative (Option B)

Widen the Transport interface in src/shared/transport.ts:

onclose?: (() => void) | undefined;

Impact

• Breaking change: No — only type declarations
• Backward compatible: Yes
• Effort: 1 line change

Verification

Test with strict TypeScript settings (exactOptionalPropertyTypes: true):

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "test", version: "1.0.0" });
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport); // Should typecheck cleanly

[mcp-claude]

fixed on main by #1766 (48aba0d) — Transport.onclose etc. were widened to explicit | undefined, so the narrower class field on the streamable-http server transport is now assignable under EOPT. still present on v1.x (v1.29.0), so a backport is needed if a v1 patch release is planned; workaround for v1 users remains the as Transport cast at the connect site.

verification

on main (38349210), the repro typechecks cleanly:

// repro.ts
import type { Transport } from '@modelcontextprotocol/server';
import { WebStandardStreamableHTTPServerTransport, McpServer } from '@modelcontextprotocol/server';

const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
const asTransport: Transport = transport;
void asTransport;

const server = new McpServer({ name: 'test', version: '1.0.0' });
async function main() {
    await server.connect(transport);
}
void main;

// tsconfig.repro.json
{
    "compilerOptions": {
        "strict": true,
        "exactOptionalPropertyTypes": true,
        "noUncheckedIndexedAccess": true,
        "target": "ES2022",
        "module": "NodeNext",
        "moduleResolution": "NodeNext",
        "esModuleInterop": true,
        "skipLibCheck": false,
        "noEmit": true
    },
    "include": ["repro.ts"]
}

$ npx tsc -p tsconfig.repro.json
$ echo $?
0

on origin/v1.x (69749aa5, package version 1.29.0), the reporter's exact call site fails as described:

// repro-v1x.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const server = new McpServer({ name: 'test', version: '1.0.0' });
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
async function main() { await server.connect(transport); }
void main;

$ npx tsc -p tsconfig.repro-v1x.json
dist/esm/server/streamableHttp.d.ts(58,22): error TS2420: Class 'StreamableHTTPServerTransport' incorrectly implements interface 'Transport'.
  Types of property 'onclose' are incompatible.
    Type '(() => void) | undefined' is not assignable to type '() => void'.
      Type 'undefined' is not assignable to type '() => void'.
repro-v1x.ts(15,26): error TS2379: Argument of type 'StreamableHTTPServerTransport' is not assignable to parameter of type 'Transport' with 'exactOptionalPropertyTypes: true'.
  Types of property 'onclose' are incompatible.
    Type '(() => void) | undefined' is not assignable to type '() => void'.
      Type 'undefined' is not assignable to type '() => void'.

packages/core-internal/src/shared/transport.ts:146 on main now reads onclose?: (() => void) | undefined;; packages/server/src/server/streamableHttp.ts:252 reads onclose?: () => void;. reopen if still seeing this on main.