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

server/streamableHttp

Classes

WebStandardStreamableHTTPServerTransport

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

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

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

const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID()
});

await server.connect(transport);

Stateless setup

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

Hono.js

app.all('/mcp', async c => {
    // Stateless example: create a server and a transport 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);
});

Cloudflare Workers

const worker = {
    async fetch(request: Request): Promise<Response> {
        // Stateless example: create a server and a transport 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(request);
    }
};

Implements

• Transport

Constructors

Constructor

new WebStandardStreamableHTTPServerTransport(options?): WebStandardStreamableHTTPServerTransport

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

Parameters

options?

WebStandardStreamableHTTPServerTransportOptions = {}

Returns

WebStandardStreamableHTTPServerTransport

Properties

onclose?

optional onclose?: () => void

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

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:285

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:286

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:283

The session ID generated for this connection.

Implementation of

Transport.sessionId

Methods

close()

close(): Promise<void>

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

Closes the connection.

Returns

Promise<void>

Implementation of

Transport.close

closeSSEStream()

closeSSEStream(requestId): void

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

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:1157

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:422

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:1164

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

setScopeChallengeResolver()

setScopeChallengeResolver(resolver): void

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

Sets the scope challenge resolver for parsed JSON-RPC requests.

Parameters

resolver

ScopeChallengeHandler

Returns

void

setSupportedProtocolVersions()

setSupportedProtocolVersions(versions): void

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

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:328

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:33

Interface for resumability support via event storage

Methods

getStreamIdForEventId()?

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

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

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:52

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:40

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:187

Options for handling a request

Properties

authInfo?

optional authInfo?: AuthInfo

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

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

parsedBody?

optional parsedBody?: unknown

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

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

---

WebStandardStreamableHTTPServerTransportOptions

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

Configuration options for WebStandardStreamableHTTPServerTransport

Properties

allowedHosts?

optional allowedHosts?: string[]

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

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:140

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:147

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:120

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:126

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

keepAliveMs?

optional keepAliveMs?: number

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

Interval in milliseconds between SSE keep-alive comment frames. Defaults to 15000; set to 0 to disable.

maxRequestBodySize?

optional maxRequestBodySize?: number

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

Upper bound, in bytes, on a POST body the transport reads itself. A body over the bound (declared Content-Length, or observed while streaming) is answered 413 before anything is parsed. Not applied when the caller supplies parsedBody. Must be a positive number.

Default

4194304 (4 MiB)

onsessionclosed?

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

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

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:101

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:154

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:92

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:181

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:28

---

StreamId

StreamId = string

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