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

client/streamableHttp

Classes

StreamableHTTPClientTransport

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

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

Parameters

url

URL

opts?

StreamableHTTPClientTransportOptions

Returns

StreamableHTTPClientTransport

Properties

hasPerRequestStream

readonly hasPerRequestStream: true = true

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

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

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

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

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

Returns

string | undefined

sessionId

Get Signature

get sessionId(): string | undefined

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

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

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

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

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

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

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

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

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

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

Options for starting or authenticating an SSE connection

Properties

onRequestStreamEnd?

optional onRequestStreamEnd?: () => void

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

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

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

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

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

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

Configuration options for reconnection behavior of the StreamableHTTPClientTransport.

Properties

initialReconnectionDelay

initialReconnectionDelay: number

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

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

maxReconnectionDelay

maxReconnectionDelay: number

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

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

maxRetries

maxRetries: number

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

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

reconnectionDelayGrowFactor

reconnectionDelayGrowFactor: number

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

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

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

Configuration options for the StreamableHTTPClientTransport.

Properties

authProvider?

optional authProvider?: AuthProvider | OAuthClientProvider

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

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, SdkHttpError (SdkErrorCode.ClientHttpAuthentication) is thrown. If 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:206

Custom fetch implementation used for all network requests.

maxStepUpRetries?

optional maxStepUpRetries?: number

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

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

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

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

Options to configure the reconnection behavior.

reconnectionScheduler?

optional reconnectionScheduler?: ReconnectionScheduler

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

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

redirectPolicy?

optional redirectPolicy?: "same-origin" | "follow"

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

How a redirect of one of the transport's requests is handled, including the OAuth requests it makes for authProvider. The option does not reach requests that a provider makes with a fetch of its own, such as those of the assertion callback of a CrossAppAccessProvider.

• 'same-origin' (default): a redirect is followed only when it stays within the origin of the request and keeps the method, and any other redirect fails the request.
• 'follow': redirects are left to the fetch implementation, as in earlier versions. It follows them to any origin unless requestInit.redirect says otherwise.

Default

'same-origin'

requestInit?

optional requestInit?: RequestInit

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

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.

A redirect of 'error' or 'manual' is passed to fetch as it is for the POST, GET and DELETE requests to the server URL. For the OAuth requests, and for any other value, redirect is consulted only when redirectPolicy is 'follow'.

sessionId?

optional sessionId?: string

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

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

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.