This is the documentation for v2 — looking for the v1 documentation?
MCP TypeScript SDK

Appearance

MCP TypeScript SDK (V2) / @modelcontextprotocol/node / streamableHttp

streamableHttp ​

Classes ​

NodeStreamableHTTPServerTransport ​

Defined in: packages/middleware/node/src/streamableHttp.ts:74

Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification. It supports both SSE streaming and direct HTTP responses.

This is a wrapper around WebStandardStreamableHTTPServerTransport that provides Node.js HTTP compatibility. It uses the @hono/node-server library to convert between Node.js HTTP and Web Standard APIs.

In stateful mode:

  • Session ID is generated and included in response headers
  • Session ID is always included in initialization responses
  • Requests with invalid session IDs are rejected with 404 Not Found
  • Non-initialization requests without a session ID are rejected with 400 Bad Request
  • State is maintained in-memory (connections, message history)

In stateless mode:

  • No Session ID is included in any responses
  • No session validation is performed

Examples ​

Stateful setup

ts
const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const transport = new NodeStreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID()
});

await server.connect(transport);

Stateless setup

ts
const transport = new NodeStreamableHTTPServerTransport({
    sessionIdGenerator: undefined
});

Using with a pre-parsed request body (e.g. Express)

ts
app.post('/mcp', (req, res) => {
    transport.handleRequest(req, res, req.body);
});

Implements ​

Constructors ​

Constructor ​

new NodeStreamableHTTPServerTransport(options?): NodeStreamableHTTPServerTransport

Defined in: packages/middleware/node/src/streamableHttp.ts:80

Parameters ​
options? ​

WebStandardStreamableHTTPServerTransportOptions = {}

Returns ​

NodeStreamableHTTPServerTransport

Accessors ​

onclose ​
Get Signature ​

get onclose(): (() => void) | undefined

Defined in: packages/middleware/node/src/streamableHttp.ts:114

Callback for when the connection is closed for any reason.

This should be invoked when close() is called as well.

Returns ​

(() => void) | undefined

Set Signature ​

set onclose(handler): void

Defined in: packages/middleware/node/src/streamableHttp.ts:110

Sets callback for when the transport is closed.

Parameters ​
handler ​

(() => void) | undefined

Returns ​

void

Callback for when the connection is closed for any reason.

This should be invoked when close() is called as well.

Implementation of ​

Transport.onclose

onerror ​
Get Signature ​

get onerror(): ((error) => void) | undefined

Defined in: packages/middleware/node/src/streamableHttp.ts:125

Callback for when an error occurs.

Note that errors are not necessarily fatal; they are used for reporting any kind of exceptional condition out of band.

Returns ​

((error) => void) | undefined

Set Signature ​

set onerror(handler): void

Defined in: packages/middleware/node/src/streamableHttp.ts:121

Sets callback for transport errors.

Parameters ​
handler ​

((error) => void) | undefined

Returns ​

void

Callback for when an error occurs.

Note that errors are not necessarily fatal; they are used for reporting any kind of exceptional condition out of band.

Implementation of ​

Transport.onerror

onmessage ​
Get Signature ​

get onmessage(): ((message, extra?) => void) | undefined

Defined in: packages/middleware/node/src/streamableHttp.ts:136

Callback for when a message (request or response) is received over the connection.

Includes the request and authInfo if the transport is authenticated.

The request can be used to get the original request information (headers, etc.)

Returns ​

((message, extra?) => void) | undefined

Set Signature ​

set onmessage(handler): void

Defined in: packages/middleware/node/src/streamableHttp.ts:132

Sets callback for incoming messages.

Parameters ​
handler ​

((message, extra?) => void) | undefined

Returns ​

void

Callback for when a message (request or response) is received over the connection.

Includes the request and authInfo if the transport is authenticated.

The request can be used to get the original request information (headers, etc.)

Implementation of ​

Transport.onmessage

sessionId ​
Get Signature ​

get sessionId(): string | undefined

Defined in: packages/middleware/node/src/streamableHttp.ts:103

Gets the session ID for this transport instance.

Returns ​

string | undefined

The session ID generated for this connection.

Implementation of ​

Transport.sessionId

Methods ​

close() ​

close(): Promise<void>

Defined in: packages/middleware/node/src/streamableHttp.ts:151

Closes the transport and all active connections.

Returns ​

Promise<void>

Implementation of ​

Transport.close

closeSSEStream() ​

closeSSEStream(requestId): void

Defined in: packages/middleware/node/src/streamableHttp.ts:216

Close an SSE stream for a specific request, triggering client reconnection. Use this to implement polling behavior during long-running operations - client will reconnect after the retry interval specified in the priming event.

Parameters ​
requestId ​

RequestId

Returns ​

void

closeStandaloneSSEStream() ​

closeStandaloneSSEStream(): void

Defined in: packages/middleware/node/src/streamableHttp.ts:224

Close the standalone GET SSE stream, triggering client reconnection. Use this to implement polling behavior for server-initiated notifications.

Returns ​

void

handleRequest() ​

handleRequest(req, res, parsedBody?): Promise<void>

Defined in: packages/middleware/node/src/streamableHttp.ts:188

Handles an incoming HTTP request, whether GET or POST.

This method converts Node.js HTTP objects to Web Standard Request/Response and delegates to the underlying WebStandardStreamableHTTPServerTransport.

Parameters ​
req ​

IncomingMessage & object

Node.js IncomingMessage, optionally with auth property from middleware

res ​

ServerResponse

Node.js ServerResponse

parsedBody? ​

unknown

Optional pre-parsed body from body-parser middleware

Returns ​

Promise<void>

send() ​

send(message, options?): Promise<void>

Defined in: packages/middleware/node/src/streamableHttp.ts:158

Sends a JSON-RPC message through the transport.

Parameters ​
message ​

JSONRPCMessage

options? ​
relatedRequestId? ​

RequestId

Returns ​

Promise<void>

Implementation of ​

Transport.send

setScopeChallengeResolver() ​

setScopeChallengeResolver(resolver): void

Defined in: packages/middleware/node/src/streamableHttp.ts:174

Sets the scope challenge resolver used by the wrapped Web Standard transport.

Parameters ​
resolver ​

ScopeChallengeHandler

Returns ​

void

setSupportedProtocolVersions() ​

setSupportedProtocolVersions(versions): void

Defined in: packages/middleware/node/src/streamableHttp.ts:169

Forwards the supported protocol versions to the wrapped Web Standard transport for MCP-Protocol-Version header validation. Called by the protocol layer during connect; without this delegation a server's supportedProtocolVersions option never reached the Node adapter's header validation.

Parameters ​
versions ​

string[]

Returns ​

void

Implementation of ​

Transport.setSupportedProtocolVersions

start() ​

start(): Promise<void>

Defined in: packages/middleware/node/src/streamableHttp.ts:144

Starts the transport. This is required by the Transport interface but is a no-op for the Streamable HTTP transport as connections are managed per-request.

Returns ​

Promise<void>

Implementation of ​

Transport.start

Type Aliases ​

StreamableHTTPServerTransportOptions ​

StreamableHTTPServerTransportOptions = WebStandardStreamableHTTPServerTransportOptions

Defined in: packages/middleware/node/src/streamableHttp.ts:29

Configuration options for NodeStreamableHTTPServerTransport

This is an alias for WebStandardStreamableHTTPServerTransportOptions for backward compatibility.