# How should an instance reconcile SSE `Last-Event-ID` replay with streamable-HTTP `Mcp-Session-Id` resumption when both headers are present **Date of Record:** 2026 November 18 **Scope:** Applies to MCP servers and clients migrating from the legacy HTTP+SSE transport to the streamable-HTTP transport, specifically when a client presents both a `Last-Event-ID` header (SSE replay semantics) and an `Mcp-Session-Id` header (streamable-HTTP session semantics) on a resumed `POST`/`GET`. Does not apply to pure SSE deployments (no session id) or pure streamable-HTTP deployments (no event id). ## Core Distinction The two transports encode *different notions of "where was I"* and they are not interchangeable. `Last-Event-ID` is a **transport-level replay cursor**: it names the last SSE event the client durably received, and the correct server behavior is to replay every event after that id from a retained buffer. `Mcp-Session-Id` is a **protocol-level session identity**: it names a logical conversation whose state lives in server-side session storage (initialization params, negotiated capabilities, subscriptions, in-flight request map). The non-obvious failure is that these two cursors can *disagree*, and a naive migration path treats them as aliases. When they disagree, replaying events the session has already acknowledged produces duplicate JSON-RPC responses; suppressing replay because the session "exists" silently drops events the client never saw. Neither header is authoritative alone. ## What Was Observed During a rolling migration, a client library was updated to streamable-HTTP but retained its SSE reconnect logic. On a transient `502` mid-stream it reconnected with the last SSE event id it had buffered (`Last-Event-ID: 41`) *and* the session id from the `initialize` response (`Mcp-Session-Id: sess_9f...`). The server had, in the interim, compacted its SSE event buffer for that session after the client's prior `202 Accepted` acknowledgements, retaining only events `>= 44`. The server logic was: *if `Mcp-Session-Id` is valid, the session is live, so ignore `Last-Event-ID` and continue from the live head.* Result: events `42` and `43` — a `notifications/tools/list_changed` and a `progress` notification — were never delivered. The client's tool cache went stale for the remainder of the session and a long-running tool appeared to hang because its final `progress` frame was lost. No error surfaced; both headers were individually "valid," which is exactly why the bug was silent. A second observed variant: a different server implementation honored `Last-Event-ID` but did *not* verify it belonged to the same session, replaying another session's buffered events (id `41` collided across sessions because event ids were per-process, not per-session). This leaked a `resources/updated` notification from an unrelated tenant. ## Condition of Validity The invariant holds only when the following are all true, and fails loudly or silently otherwise: 1. Event ids are **scoped to the session**, not to the process or connection. If ids are global, replay-by-id must additionally be filtered by `Mcp-Session-Id`. 2. The server retains a replay buffer keyed by session, with an explicit **low-water mark** (oldest retained id). Replay is only correct for `Last-Event-ID >= low_water_mark - 1`. 3. The session record and the event buffer are **co-committed**: a session that exists but whose buffer has been compacted past the client's cursor cannot satisfy replay and must signal a gap, not silently resume. 4. The client treats `Last-Event-ID` as authoritative for *delivery position* and `Mcp-Session-Id` as authoritative for *identity and server-side state*, and never uses one to override the other. If any condition is false, the correct behavior is a **resumption gap error**, not a best-effort continuation. ## Decision Boundary On a resumed request carrying both headers, the server must compute `replay_from = Last-Event-ID + 1` and compare against `low_water_mark` for that session: - If `replay_from >= low_water_mark`: replay `[replay_from, head]` from the session buffer, then continue live. The session id confirms the buffer is the right one; the event id confirms the position. Both are used, neither overrides. - If `replay_from < low_water_mark`: the client's cursor predates retained history. **Reject** with a structured resumption error (HTTP `409` with a JSON-RPC error body carrying the gap range) so the client can re-`initialize` or re-fetch full state. Do not silently jump to the live head. - If `Mcp-Session-Id` is unknown/expired but `Last-Event-ID` is present: the session is gone; replay is impossible regardless of buffer. Return the same resumption error; the event id is meaningless without its session. - If `Last-Event-ID` is absent but `Mcp-Session-Id` is valid: this is a fresh stream attach, not a resume. Start at the live head; do not replay. The boundary the original code crossed: it treated "session valid" as a sufficient condition for "resume correctly," collapsing two independent predicates into one. ## Operational Effect After enforcing the decision boundary, the stale-cache incident class disappeared: clients that fell behind the low-water mark received an explicit `409` and re-initialized, which is observable and recoverable, instead of silently missing notifications. Cross-session replay leakage was eliminated by scoping event ids to sessions and filtering replay by `Mcp-Session-Id`. The cost is that servers must now maintain and expose a per-session low-water mark and emit a distinct resumption-gap error; clients must handle that error rather than assuming reconnect always succeeds. The general lesson for the migration: **transport replay cursors and protocol session identities answer different questions — "which bytes did you see" versus "which conversation are you in" — and any code path that lets one stand in for the other is a silent data-loss path.** ```python class ResumptionGapError(RuntimeError): """Raised when a resume request cannot be satisfied from retained history.""" def __init__(self, session_id: str, requested_from: int, low_water_mark: int): self.session_id = session_id self.requested_from = requested_from self.low_water_mark = low_water_mark super().__init__( f"session {session_id}: cannot replay from event {requested_from}; " f"oldest retained is {low_water_mark}" ) def resolve_resume( session_id: str | None, last_event_id: int | None, session_store: dict, ) -> tuple[int, bool]: """Return (replay_from, is_resume) or raise ResumptionGapError. Both headers are honored; neither overrides the other. """ if session_id is None: # No session identity: cannot resume, treat as fresh stream. return (0, False) session = session_store.get(session_id) if session is None: # Session expired/unknown; event id is meaningless without it. raise ResumptionGapError(session_id, last_event_id or 0, 0) if last_event_id is None: # Valid session, no cursor: fresh attach at live head. return (session["head"] + 1, False) replay_from = last_event_id + 1 if replay_from < session["low_water_mark"]: raise ResumptionGapError(session_id, replay_from, session["low_water_mark"]) return (replay_from, True) ```