Class NodeStreamableHTTPServerTransport

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

Example: Stateful setup

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

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

await server.connect(transport);

Example: Stateless setup

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

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

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

Implements

Transport

Index

Constructors

constructor

new NodeStreamableHTTPServerTransport(
options?: WebStandardStreamableHTTPServerTransportOptions,
): NodeStreamableHTTPServerTransport
Parameters
- options: WebStandardStreamableHTTPServerTransportOptions = {}
Returns NodeStreamableHTTPServerTransport
- Defined in packages/middleware/node/src/streamableHttp.ts:73

Accessors

onclose

get onclose(): (() => void) | undefined
Callback for when the connection is closed for any reason.

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

Returns (() => void) | undefined
Implementation of Transport.onclose
- Defined in packages/middleware/node/src/streamableHttp.ts:107
set onclose(handler: (() => void) | undefined): void
Sets callback for when the transport is closed.
Parameters
- handler: (() => void) | undefined
Returns void
Implementation of Transport.onclose
- Defined in packages/middleware/node/src/streamableHttp.ts:103

onerror

get onerror(): ((error: Error) => void) | undefined
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: Error) => void) | undefined
Implementation of Transport.onerror
- Defined in packages/middleware/node/src/streamableHttp.ts:118
set onerror(handler: ((error: Error) => void) | undefined): void
Sets callback for transport errors.
Parameters
- handler: ((error: Error) => void) | undefined
Returns void
Implementation of Transport.onerror
- Defined in packages/middleware/node/src/streamableHttp.ts:114

onmessage

get onmessage(): | ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void)
| undefined
Callback for when a message (request or response) is received over the connection.

Includes the requestInfo and authInfo if the transport is authenticated.

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

Returns ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void) | undefined
Implementation of Transport.onmessage
- Defined in packages/middleware/node/src/streamableHttp.ts:129
set onmessage(
    handler:
        | ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void)
        | undefined,
): void
Sets callback for incoming messages.
Parameters
- handler: ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void) | undefined
Returns void
Implementation of Transport.onmessage
- Defined in packages/middleware/node/src/streamableHttp.ts:125

sessionId

get sessionId(): string | undefined
Gets the session ID for this transport instance.

Returns string | undefined
Implementation of Transport.sessionId
- Defined in packages/middleware/node/src/streamableHttp.ts:96

Methods

close

close(): Promise<void>
Closes the transport and all active connections.

Returns Promise<void>
Implementation of Transport.close
- Defined in packages/middleware/node/src/streamableHttp.ts:144

closeSSEStream

closeSSEStream(requestId: RequestId): void
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
- Defined in packages/middleware/node/src/streamableHttp.ts:193

closeStandaloneSSEStream

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

Returns void
- Defined in packages/middleware/node/src/streamableHttp.ts:201

handleRequest

handleRequest(
    req: IncomingMessage & { auth?: AuthInfo },
    res: ServerResponse,
    parsedBody?: unknown,
): Promise<void>
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 & { auth?: AuthInfo }
  Node.js IncomingMessage, optionally with auth property from middleware
- res: ServerResponse
  Node.js ServerResponse
- OptionalparsedBody: unknown
  Optional pre-parsed body from body-parser middleware
Returns Promise<void>
- Defined in packages/middleware/node/src/streamableHttp.ts:165

send

send(
message: JSONRPCMessage,
options?: { relatedRequestId?: RequestId },
): Promise<void>
Sends a JSON-RPC message through the transport.
Parameters
- message: JSONRPCMessage
- Optionaloptions: { relatedRequestId?: RequestId }
Returns Promise<void>
Implementation of Transport.send
- Defined in packages/middleware/node/src/streamableHttp.ts:151

start

start(): Promise<void>
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
- Defined in packages/middleware/node/src/streamableHttp.ts:137

Class NodeStreamableHTTPServerTransport

Example: Stateful setup

Example: Stateless setup

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

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns NodeStreamableHTTPServerTransport

Accessors

onclose

Returns (() => void) | undefined

Parameters

Returns void

onerror

Returns ((error: Error) => void) | undefined

Parameters

Returns void

onmessage

Returns ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void) | undefined

Parameters

Returns void

sessionId

Returns string | undefined

Methods

close

Returns Promise<void>

closeSSEStream

Parameters

Returns void

closeStandaloneSSEStream

Returns void

handleRequest

Parameters

Returns Promise<void>

send

Parameters

Returns Promise<void>

start

Returns Promise<void>

Settings

On This Page