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

client/streamableHttp

Classes

StreamableHTTPClientTransport

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

Client transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification. It will connect to a server using HTTP POST for sending messages and HTTP GET with Server-Sent Events for receiving messages.

Implements

• Transport

Constructors

Constructor

new StreamableHTTPClientTransport(url, opts?): StreamableHTTPClientTransport

Defined in: packages/client/src/client/streamableHttp.ts:352

Parameters

url

URL

opts?

StreamableHTTPClientTransportOptions

Returns

StreamableHTTPClientTransport

Properties

hasPerRequestStream

readonly hasPerRequestStream: true = true

Defined in: packages/client/src/client/streamableHttp.ts:350

Streamable HTTP opens one POST (and SSE response stream) per outbound request and honors TransportSendOptions.requestSignal. On a 2026-era connection the protocol layer aborts that per-request stream as the spec cancellation signal instead of POSTing notifications/cancelled.

Implementation of

Transport.hasPerRequestStream

onclose?

optional onclose?: () => void

Defined in: packages/client/src/client/streamableHttp.ts:340

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/client/src/client/streamableHttp.ts:341

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) => void

Defined in: packages/client/src/client/streamableHttp.ts:342

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

Returns

void

Implementation of

Transport.onmessage

Accessors

protocolVersion

Get Signature

get protocolVersion(): string | undefined

Defined in: packages/client/src/client/streamableHttp.ts:1251

Returns

string | undefined

sessionId

Get Signature

get sessionId(): string | undefined

Defined in: packages/client/src/client/streamableHttp.ts:1195

The session ID generated for this connection.

Returns

string | undefined

The session ID generated for this connection.

Implementation of

Transport.sessionId

Methods

close()

close(): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:929

Closes the connection.

Returns

Promise<void>

Implementation of

Transport.close

finishAuth()

Call Signature

finishAuth(callbackParams): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:893

Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.

Preferred: pass the callback URL's searchParams directly. The SDK extracts code and iss, validates iss against the recorded issuer (RFC 9207) before reading any other parameter, and on mismatch throws an IssuerMismatchError that carries none of the callback's error/error_description/error_uri text — those are attacker-controlled in a mix-up attack and MUST NOT be displayed. The (code, iss?) positional form remains supported for back-compat.

The SDK does not validate state; compare it to your stored value before calling finishAuth.

Parameters

callbackParams

URLSearchParams

The URLSearchParams from the authorization callback URL (e.g. new URL(callbackUrl).searchParams). code and iss are read from it.

Returns

Promise<void>

Call Signature

finishAuth(authorizationCode, iss?): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:901

Parameters

authorizationCode

string

The code query parameter from the authorization callback URL.

iss?

string

The form-urldecoded iss query parameter from the same callback URL, if present. Validated per RFC 9207 against the recorded issuer before the code is redeemed. When the authorization server advertises authorization_response_iss_parameter_supported: true, omitting this causes the exchange to be rejected with IssuerMismatchError.

Returns

Promise<void>

resumeStream()

resumeStream(lastEventId, options?): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:1262

Resume an SSE stream from a previous event ID. Opens a GET SSE connection with Last-Event-ID header to replay missed events.

Parameters

lastEventId

string

The event ID to resume from

options?

Optional callback to receive new resumption tokens

onresumptiontoken?

(token) => void

Returns

Promise<void>

send()

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

Defined in: packages/client/src/client/streamableHttp.ts:939

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 | JSONRPCMessage[]

options?

headers?

Readonly<Record<string, string>>

onRequestStreamEnd?

() => void

onresumptiontoken?

(token) => void

requestSignal?

AbortSignal

resumptionToken?

string

Returns

Promise<void>

Implementation of

Transport.send

setProtocolVersion()

setProtocolVersion(version): void

Defined in: packages/client/src/client/streamableHttp.ts:1248

Sets the protocol version used for the connection (called when the initialize response is received).

Parameters

version

string

Returns

void

Implementation of

Transport.setProtocolVersion

start()

start(): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:867

Starts processing messages on the transport, including any connection steps that might need to be taken.

This method should only be called after callbacks are installed, or else messages may be lost.

NOTE: This method should not be called explicitly when using Client or Server classes, as they will implicitly call start().

Returns

Promise<void>

Implementation of

Transport.start

terminateSession()

terminateSession(): Promise<void>

Defined in: packages/client/src/client/streamableHttp.ts:1210

Terminates the current session by sending a DELETE request to the server.

Clients that no longer need a particular session (e.g., because the user is leaving the client application) SHOULD send an HTTP DELETE to the MCP endpoint with the Mcp-Session-Id header to explicitly terminate the session.

The server MAY respond with HTTP 405 Method Not Allowed, indicating that the server does not allow clients to terminate sessions.

Returns

Promise<void>

Interfaces

StartSSEOptions

Defined in: packages/client/src/client/streamableHttp.ts:57

Options for starting or authenticating an SSE connection

Properties

onRequestStreamEnd?

optional onRequestStreamEnd?: () => void

Defined in: packages/client/src/client/streamableHttp.ts:94

The per-request stream-end callback supplied via TransportSendOptions.onRequestStreamEnd. Fired when the SSE response stream for the originating POST ends or errors for any non-deliberate reason (server closed, network dropped, reconnection exhausted) — never when requestSignal was aborted.

Returns

void

onresumptiontoken?

optional onresumptiontoken?: (token) => void

Defined in: packages/client/src/client/streamableHttp.ts:70

A callback that is invoked when the resumption token changes.

This allows clients to persist the latest token for potential reconnection.

Parameters

token

string

Returns

void

replayMessageId?

optional replayMessageId?: string | number

Defined in: packages/client/src/client/streamableHttp.ts:76

Override Message ID to associate with the replay message so that the response can be associated with the new resumed request.

requestSignal?

optional requestSignal?: AbortSignal

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

The per-request abort signal supplied by the caller via TransportSendOptions.requestSignal. When this signal is aborted the originating POST and its SSE response stream are torn down intentionally — _handleSseStream treats it exactly like the transport-level abort: no onerror, no reconnect.

resumptionToken?

optional resumptionToken?: string

Defined in: packages/client/src/client/streamableHttp.ts:63

The resumption token used to continue long-running requests that were interrupted.

This allows clients to reconnect and continue from where they left off.

---

StreamableHTTPReconnectionOptions

Defined in: packages/client/src/client/streamableHttp.ts:100

Configuration options for reconnection behavior of the StreamableHTTPClientTransport.

Properties

initialReconnectionDelay

initialReconnectionDelay: number

Defined in: packages/client/src/client/streamableHttp.ts:111

Initial backoff time between reconnection attempts in milliseconds. Default is 1000 (1 second).

maxReconnectionDelay

maxReconnectionDelay: number

Defined in: packages/client/src/client/streamableHttp.ts:105

Maximum backoff time between reconnection attempts in milliseconds. Default is 30000 (30 seconds).

maxRetries

maxRetries: number

Defined in: packages/client/src/client/streamableHttp.ts:123

Maximum number of reconnection attempts before giving up. Default is 2.

reconnectionDelayGrowFactor

reconnectionDelayGrowFactor: number

Defined in: packages/client/src/client/streamableHttp.ts:117

The factor by which the reconnection delay increases after each attempt. Default is 1.5.

Type Aliases

ReconnectionScheduler

ReconnectionScheduler = (reconnect, delay, attemptCount) => (() => void) | void

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

Custom scheduler for SSE stream reconnection attempts.

Called instead of setTimeout when the transport needs to schedule a reconnection. Useful in environments where setTimeout is unsuitable (serverless functions that terminate before the timer fires, mobile apps that need platform background scheduling, desktop apps handling sleep/wake).

Parameters

reconnect

() => void

Call this to perform the reconnection attempt.

delay

number

Suggested delay in milliseconds (from backoff calculation).

attemptCount

number

Zero-indexed retry attempt number.

Returns

(() => void) | void

An optional cancel function. If returned, it will be called on transport.close() to abort the pending reconnection.

Example

const scheduler: ReconnectionScheduler = (reconnect, delay) => {
    const id = platformBackgroundTask.schedule(reconnect, delay);
    return () => platformBackgroundTask.cancel(id);
};

---

StreamableHTTPClientTransportOptions

StreamableHTTPClientTransportOptions = object

Defined in: packages/client/src/client/streamableHttp.ts:154

Configuration options for the StreamableHTTPClientTransport.

Properties

authProvider?

optional authProvider?: AuthProvider | OAuthClientProvider

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

An OAuth client provider to use for authentication.

token() is called before every request to obtain the bearer token. When the server responds with 401, onUnauthorized() is called (if provided) to refresh credentials, then the request is retried once. If the retry also gets 401, or onUnauthorized is not provided, UnauthorizedError is thrown.

For simple bearer tokens: { token: async () => myApiKey }.

For OAuth flows, pass an OAuthClientProvider implementation directly — the transport adapts it to AuthProvider internally. Interactive flows: after UnauthorizedError, redirect the user, then call finishAuth with the authorization code before reconnecting.

fetch?

optional fetch?: FetchLike

Defined in: packages/client/src/client/streamableHttp.ts:198

Custom fetch implementation used for all network requests.

maxStepUpRetries?

optional maxStepUpRetries?: number

Defined in: packages/client/src/client/streamableHttp.ts:257

Maximum number of step-up re-authorization attempts the transport makes per send (and per GET stream open) before giving up. Only consulted when onInsufficientScope is 'reauthorize'. Cross-request tracking ("this resource+operation already failed N times across the session") is host responsibility.

Default

1

onInsufficientScope?

optional onInsufficientScope?: "reauthorize" | "throw"

Defined in: packages/client/src/client/streamableHttp.ts:246

How the transport reacts to a 403 Forbidden response carrying WWW-Authenticate: Bearer error="insufficient_scope".

• 'reauthorize' (default): the transport runs the step-up authorization flow — computes the union of the previously-requested scope and the challenged scope, calls auth() (forcing a fresh authorization request when the union strictly exceeds the current token's granted scope, since refresh cannot widen scope per RFC 6749 §6), and retries the request once. Retries are bounded by maxStepUpRetries. If no OAuthClientProvider is configured, step-up cannot run and the transport throws InsufficientScopeError instead.
• 'throw': the transport throws InsufficientScopeError carrying the challenge parameters and does not re-authorize. Use this for client_credentials / m2m clients where re-authorization cannot widen scope, or for interactive clients that want to gate the consent prompt behind UX.

Default

'reauthorize'

protocolVersion?

optional protocolVersion?: string

Defined in: packages/client/src/client/streamableHttp.ts:222

The MCP protocol version to include in the mcp-protocol-version header on all requests. When reconnecting with a preserved sessionId, set this to the version negotiated during the original handshake so the reconnected transport continues sending the required header.

reconnectionOptions?

optional reconnectionOptions?: StreamableHTTPReconnectionOptions

Defined in: packages/client/src/client/streamableHttp.ts:203

Options to configure the reconnection behavior.

reconnectionScheduler?

optional reconnectionScheduler?: ReconnectionScheduler

Defined in: packages/client/src/client/streamableHttp.ts:209

Custom scheduler for reconnection attempts. If not provided, setTimeout is used. See ReconnectionScheduler.

requestInit?

optional requestInit?: RequestInit

Defined in: packages/client/src/client/streamableHttp.ts:193

Customizes HTTP requests to the server.

headers are sent on every request, but the transport-managed headers take precedence over a same-named entry here: Authorization when authProvider yields a token, mcp-session-id, and mcp-protocol-version. A caller-supplied Authorization value is therefore only sent while the provider has no token, which lets a static API key fall back to OAuth once the provider obtains one.

sessionId?

optional sessionId?: string

Defined in: packages/client/src/client/streamableHttp.ts:215

Session ID for the connection. This is used to identify the session on the server. When not provided and connecting to a server that supports session IDs, the server will generate a new session ID.

skipIssuerMetadataValidation?

optional skipIssuerMetadataValidation?: boolean

Defined in: packages/client/src/client/streamableHttp.ts:181

Opt-out for the RFC 8414 §3.3 issuer-echo check during authorization-server metadata discovery. Security-weakening — see AuthOptions.skipIssuerMetadataValidation. Only honoured when authProvider is an OAuthClientProvider.