mcp.transport.sse_context

Undocumented in source.

Members

Classes

HttpStreamContext
class HttpStreamContext

A RequestContext backed by an HTTP response that is (lazily) upgraded to a Server-Sent Events stream the first time the handler emits server->client traffic. Progress/logging become SSE notification events; sampling/ elicitation send an SSE request event then block (via the coordinator) for the client's response on a later POST. The final JSON-RPC response is the terminating SSE event.

ServerPushChannel
class ServerPushChannel

A long-lived server->client SSE channel for *unsolicited* traffic — the stream a client opens with an HTTP GET to the MCP endpoint (basic/transports §Listening for Messages from the Server). One instance is shared across a server mount. Unlike HttpStreamContext, which is bound to one in-flight POST, emit frames the JSON-RPC message as an SSE event with a globally-unique id (via the shared StreamCoordinator ordinal scheme) and writes it to exactly ONE live GET listener, honouring the transport's Multiple Connections rule: "The server MUST send each of its JSON-RPC messages on only one of the connected streams; that is, it MUST NOT broadcast the same message across multiple streams." A listener that fails to write (a disconnected client) is skipped and dropped, so the channel self-heals and the message still lands on a live stream.

StreamCoordinator
class StreamCoordinator

Correlates outbound server->client requests with the client's responses, which arrive on a *separate* POST. One instance is shared across all handlers of a single server mount.

Functions

applySseStreamHeaders
void applySseStreamHeaders(HTTPServerResponse res, bool isDraft)

Set the SSE upgrade headers (see sseStreamHeaders) on a response, leaving the caller to set contentType. Applies the draft-only X-Accel-Buffering header only when isDraft is true.

extractProgressToken
Json extractProgressToken(Json params)

Extract _meta.progressToken from a request's params, or Json.undefined.

formatPrimingEvent
string formatPrimingEvent(string id)

Frame the 2025-11-25 leading "priming" SSE event: an id: line carrying the stream's next event id followed by an empty data: field (basic/transports §Sending Messages item 6 — "an SSE event consisting of an event ID and an empty data field in order to prime the client to reconnect"). The empty data line is required so it parses as a real SSE event (and thus updates the client's last event id), while carrying no JSON-RPC payload.

formatRetryEvent
string formatRetryEvent(uint ms)

Frame a standalone Server-Sent Events retry: event carrying the reconnection time in milliseconds (per the SSE standard's retry field: https://html.spec.whatwg.org/multipage/server-sent-events.html). The server SHOULD send this before closing a connection it is not terminating; the client MUST then wait the given number of milliseconds before reconnecting (basic/transports §Sending Messages item 6). A bare retry: event carries no data: line, so it updates the client's reconnection time without dispatching any JSON-RPC payload.

formatSseEvent
string formatSseEvent(string id, Json msg)

Frame a JSON-RPC message as a Server-Sent Events block. Per the transport Resumability/Redelivery section, the server attaches an id: line so a client can reconnect with Last-Event-ID; the id MUST be globally unique within the session, which the caller guarantees via a per-stream ordinal plus a monotonic event sequence. An empty id omits the line.

parseEventId
bool parseEventId(string id, long ordinal, long seq)

Parse an SSE event id of the form <ordinal>-<seq> (the per-stream cursor ServerPushChannel stamps on every event) back into its components. Returns true with ordinal/seq populated on success, false for any malformed input (empty, no dash, non-numeric, negative). Used to interpret a reconnecting client's Last-Event-ID so the server can replay events after that cursor on the stream it identifies (basic/transports §Resumability and Redelivery).

sendsPrimingEvent
bool sendsPrimingEvent(ProtocolVersion v)

Whether a POST-initiated SSE stream must lead with the priming event (an event id + empty data field) for the given negotiated version. This is a 2025-11-25-only SHOULD (basic/transports §Sending Messages item 6): it did not exist in 2025-03-26 / 2025-06-18, and the draft removed Last-Event-ID resumability altogether, so the priming event must NOT alter those versions' wire output. Gated here as a single pure predicate so the version boundary is directly testable.

sendsRetryOnClose
bool sendsRetryOnClose(ProtocolVersion v)

Whether the server SHOULD emit an SSE retry: field before closing a connection that it is *not* terminating (so the client knows how long to wait before reconnecting). This is a 2025-11-25-only SHOULD (basic/transports §Sending Messages item 6 / §Listening for Messages item 4): "If the server does close the connection prior to terminating the SSE stream, it SHOULD send an SSE event with a standard retry field before closing the connection." It builds on the 2025-11-25 connection/stream split (reconnect via Last-Event-ID), which does not exist in 2025-03-26 / 2025-06-18, and the draft dropped Last-Event-ID resumability — so this MUST NOT alter those versions' wire output. Gated here as a single pure predicate so the version boundary is directly testable.

sseStreamHeaders
string[string] sseStreamHeaders(bool isDraft)

The HTTP response headers a server sets when it upgrades a response to a Server-Sent Events stream (Content-Type: text/event-stream).

Structs

SubscriptionFilter
struct SubscriptionFilter

The per-stream opt-in a client expressed when it opened a draft subscriptions/listen stream (draft basic/utilities/subscriptions §Notification Filter). It records exactly which change-notification types this one stream asked for, so the server can honour the MUST NOT: "The server MUST NOT send notification types the client has not explicitly requested." With Multiple Concurrent Subscriptions each listen stream carries its own filter (keyed by its listen request id), so a notification is delivered only to streams that opted into it — never to a concurrent stream that requested a different type.