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

Appearance

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

server/streamableHttp ​

Classes ​

WebStandardStreamableHTTPServerTransport ​

Defined in: packages/server/src/server/streamableHttp.ts:231

Server transport for Web Standards Streamable HTTP: this implements the MCP Streamable HTTP transport specification using Web Standard APIs (Request, Response, ReadableStream).

This transport works on any runtime that supports Web Standards: Node.js 18+, Cloudflare Workers, Deno, Bun, etc.

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 WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID()
});

await server.connect(transport);

Stateless setup

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

Hono.js

ts
app.all('/mcp', async c => {
    return transport.handleRequest(c.req.raw);
});

Cloudflare Workers

ts
const worker = {
    async fetch(request: Request): Promise<Response> {
        return transport.handleRequest(request);
    }
};

Implements ​

Constructors ​

Constructor ​

new WebStandardStreamableHTTPServerTransport(options?): WebStandardStreamableHTTPServerTransport

Defined in: packages/server/src/server/streamableHttp.ts:256

Parameters ​
options? ​

WebStandardStreamableHTTPServerTransportOptions = {}

Returns ​

WebStandardStreamableHTTPServerTransport

Properties ​

onclose? ​

optional onclose?: () => void

Defined in: packages/server/src/server/streamableHttp.ts:252

Callback for when the connection is closed for any reason.

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

Returns ​

void

Implementation of ​

Transport.onclose

onerror? ​

optional onerror?: (error) => void

Defined in: packages/server/src/server/streamableHttp.ts:253

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.

Parameters ​
error ​

Error

Returns ​

void

Implementation of ​

Transport.onerror

onmessage? ​

optional onmessage?: (message, extra?) => void

Defined in: packages/server/src/server/streamableHttp.ts:254

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.)

Parameters ​
message ​

JSONRPCMessage

extra? ​

MessageExtraInfo

Returns ​

void

Implementation of ​

Transport.onmessage

sessionId? ​

optional sessionId?: string

Defined in: packages/server/src/server/streamableHttp.ts:251

The session ID generated for this connection.

Implementation of ​

Transport.sessionId

Methods ​

close() ​

close(): Promise<void>

Defined in: packages/server/src/server/streamableHttp.ts:977

Closes the connection.

Returns ​

Promise<void>

Implementation of ​

Transport.close

closeSSEStream() ​

closeSSEStream(requestId): void

Defined in: packages/server/src/server/streamableHttp.ts:999

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/server/src/server/streamableHttp.ts:1013

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

Returns ​

void

handleRequest() ​

handleRequest(req, options?): Promise<Response>

Defined in: packages/server/src/server/streamableHttp.ts:354

Handles an incoming HTTP request, whether GET, POST, or DELETE Returns a Response object (Web Standard)

Parameters ​
req ​

Request

options? ​

HandleRequestOptions

Returns ​

Promise<Response>

send() ​

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

Defined in: packages/server/src/server/streamableHttp.ts:1020

Sends a JSON-RPC message (request or response).

If present, relatedRequestId is used to indicate to the transport which incoming request to associate this outgoing message with.

Parameters ​
message ​

JSONRPCMessage

options? ​
relatedRequestId? ​

RequestId

Returns ​

Promise<void>

Implementation of ​

Transport.send

setSupportedProtocolVersions() ​

setSupportedProtocolVersions(versions): void

Defined in: packages/server/src/server/streamableHttp.ts:284

Sets the supported protocol versions for header validation. Called by the server during connect() to pass its supported versions.

Parameters ​
versions ​

string[]

Returns ​

void

Implementation of ​

Transport.setSupportedProtocolVersions

start() ​

start(): Promise<void>

Defined in: packages/server/src/server/streamableHttp.ts:273

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

Interfaces ​

EventStore ​

Defined in: packages/server/src/server/streamableHttp.ts:28

Interface for resumability support via event storage

Methods ​

getStreamIdForEventId()? ​

optional getStreamIdForEventId(eventId): Promise<string | undefined>

Defined in: packages/server/src/server/streamableHttp.ts:45

Get the stream ID associated with a given event ID.

Parameters ​
eventId ​

string

The event ID to look up

Returns ​

Promise<string | undefined>

The stream ID, or undefined if not found

Optional: If not provided, the SDK will use the streamId returned by replayEventsAfter for stream mapping.

replayEventsAfter() ​

replayEventsAfter(lastEventId, __namedParameters): Promise<string>

Defined in: packages/server/src/server/streamableHttp.ts:47

Parameters ​
lastEventId ​

string

__namedParameters ​
send ​

(eventId, message) => Promise<void>

Returns ​

Promise<string>

storeEvent() ​

storeEvent(streamId, message): Promise<string>

Defined in: packages/server/src/server/streamableHttp.ts:35

Stores an event for later retrieval

Parameters ​
streamId ​

string

ID of the stream the event belongs to

message ​

JSONRPCMessage

The JSON-RPC message to store

Returns ​

Promise<string>

The generated event ID for the stored event

HandleRequestOptions ​

Defined in: packages/server/src/server/streamableHttp.ts:167

Options for handling a request

Properties ​

authInfo? ​

optional authInfo?: AuthInfo

Defined in: packages/server/src/server/streamableHttp.ts:177

Authentication info from middleware. If provided, will be passed to message handlers.

parsedBody? ​

optional parsedBody?: unknown

Defined in: packages/server/src/server/streamableHttp.ts:172

Pre-parsed request body. If provided, the transport will use this instead of parsing req.json(). Useful when using body-parser middleware that has already parsed the body.

WebStandardStreamableHTTPServerTransportOptions ​

Defined in: packages/server/src/server/streamableHttp.ts:80

Configuration options for WebStandardStreamableHTTPServerTransport

Properties ​

allowedHosts? ​

optional allowedHosts?: string[]

Defined in: packages/server/src/server/streamableHttp.ts:128

List of allowed Host header values for DNS rebinding protection. If not specified, host validation is disabled.

Deprecated ​

Use external middleware for host validation instead.

allowedOrigins? ​

optional allowedOrigins?: string[]

Defined in: packages/server/src/server/streamableHttp.ts:135

List of allowed Origin header values for DNS rebinding protection. If not specified, origin validation is disabled.

Deprecated ​

Use external middleware for origin validation instead.

enableDnsRebindingProtection? ​

optional enableDnsRebindingProtection?: boolean

Defined in: packages/server/src/server/streamableHttp.ts:142

Enable DNS rebinding protection (requires allowedHosts and/or allowedOrigins to be configured). Default is false for backwards compatibility.

Deprecated ​

Use external middleware for DNS rebinding protection instead.

enableJsonResponse? ​

optional enableJsonResponse?: boolean

Defined in: packages/server/src/server/streamableHttp.ts:115

If true, the server will return JSON responses instead of starting an SSE stream. This can be useful for simple request/response scenarios without streaming. Default is false (SSE streams are preferred).

eventStore? ​

optional eventStore?: EventStore

Defined in: packages/server/src/server/streamableHttp.ts:121

Event store for resumability support If provided, resumability will be enabled, allowing clients to reconnect and resume messages

onsessionclosed? ​

optional onsessionclosed?: (sessionId) => void | Promise<void>

Defined in: packages/server/src/server/streamableHttp.ts:108

A callback for session close events This is called when the server closes a session due to a DELETE request. Useful in cases when you need to clean up resources associated with the session. Note that this is different from the transport closing, if you are handling HTTP requests from multiple nodes you might want to close each WebStandardStreamableHTTPServerTransport after a request is completed while still keeping the session open/running.

Parameters ​
sessionId ​

string

The session ID that was closed

Returns ​

void | Promise<void>

onsessioninitialized? ​

optional onsessioninitialized?: (sessionId) => void | Promise<void>

Defined in: packages/server/src/server/streamableHttp.ts:96

A callback for session initialization events This is called when the server initializes a new session. Useful in cases when you need to register multiple mcp sessions and need to keep track of them.

Parameters ​
sessionId ​

string

The generated session ID

Returns ​

void | Promise<void>

retryInterval? ​

optional retryInterval?: number

Defined in: packages/server/src/server/streamableHttp.ts:149

Retry interval in milliseconds to suggest to clients in SSE retry field. When set, the server will send a retry field in SSE priming events to control client reconnection timing for polling behavior.

sessionIdGenerator? ​

optional sessionIdGenerator?: () => string

Defined in: packages/server/src/server/streamableHttp.ts:87

Function that generates a session ID for the transport. The session ID SHOULD be globally unique and cryptographically secure (e.g., a securely generated UUID, a JWT, or a cryptographic hash)

If not provided, session management is disabled (stateless mode).

Returns ​

string

supportedProtocolVersions? ​

optional supportedProtocolVersions?: string[]

Defined in: packages/server/src/server/streamableHttp.ts:161

List of protocol versions that this transport will accept. Used to validate the mcp-protocol-version header in incoming requests.

Note: When using Server.connect(), the server automatically passes its supportedProtocolVersions to the transport, so you typically don't need to set this option directly.

Default ​

SUPPORTED_PROTOCOL_VERSIONS

Type Aliases ​

EventId ​

EventId = string

Defined in: packages/server/src/server/streamableHttp.ts:23

StreamId ​

StreamId = string

Defined in: packages/server/src/server/streamableHttp.ts:22