# When must an instance refuse to resume an MCP HTTP-native transport stream: the Last-Event-ID / session-lifetime invariant **Date of Record:** 2026 November 17 **Scope:** Applies to MCP servers and clients using the HTTP-native (Streamable HTTP) transport with SSE stream resumption via `Last-Event-ID` and `Mcp-Session-Id`. Does not apply to stdio transport, nor to stateless HTTP deployments that never issue session IDs or event IDs. ## Core Distinction There are two superficially similar operations that must never be conflated: 1. **Resumption** — the client presents a `Last-Event-ID` for a stream that the server *can* still replay from, because the server retained the event buffer and the session that owns it. 2. **Reconnection** — the client reconnects with a `Mcp-Session-Id` (and possibly a stale `Last-Event-ID`) but the server has already terminated, expired, or never had that session. The non-obvious boundary: a server that answers a resumption request with `200 OK` and a fresh SSE stream that starts *after* the gap is not performing resumption. It is silently dropping events. The invariant is that **resumption may only succeed if the server can guarantee delivery of every event with an ID strictly greater than the presented `Last-Event-ID` that was generated within the same session.** If the server cannot honor that guarantee — expired session, evicted buffer, or an event ID it cannot place in the sequence — it MUST fail the request (typically `404 Not Found` for an unknown/expired session, `400 Bad Request` for an unusable `Last-Event-ID`) rather than open a stream. Opening a stream at the wrong position converts a detectable gap into an undetectable one. ## What Was Observed In a deployment where the MCP server kept per-session event buffers in an LRU cache with a 30-second idle TTL while the session record itself lived for 30 minutes, the following sequence recurred: - A long-running tool invocation emitted events `e100` … `e140` on a POST-initiated SSE stream. - The client's connection dropped at `e118` due to a load-balancer idle timeout. - The client reconnected with `Last-Event-ID: e118` and the correct `Mcp-Session-Id` roughly 45 seconds later. - The session record still existed, so the server accepted the session. The event buffer for that stream had been evicted by the LRU, so the server had no `e119`–`e140` to replay. - The server opened a new stream starting at the *next* event generated after reconnection (`e141`). The client observed a contiguous-looking stream and never learned that `e119`–`e140` (including a `notifications/progress` and a final tool result) were lost. The failure is not a crash. It is a *plausible* stream. Downstream agent logic proceeded as if the tool had completed with no intermediate progress, because the terminal event was among the dropped ones and the client's request remained logically pending until a later timeout fired. ## Condition of Validity Resumption is valid if and only if all of the following hold at the moment of the request: - The `Mcp-Session-Id` maps to a session that is in an active (not terminated, not expired) state. - The presented `Last-Event-ID` is parseable and belongs to the event-ID sequence of *that* session's stream. Event IDs are per-stream/per-session scoped; an ID from a different session is not a valid resume point even if numerically plausible. - The server retains every event with ID greater than the presented ID that was emitted on that stream, *or* it can reconstruct them from durable storage. - The server can distinguish "no events after `Last-Event-ID` yet" (legitimate; hold the stream open) from "events after `Last-Event-ID` existed but are gone" (must fail). If the fourth condition cannot be evaluated — for example, if the buffer was evicted and the server only knows the *highest* emitted ID rather than the retained set — the server must treat it as a failure, because it cannot prove the gap is empty. ## Decision Boundary The decision table the server must implement: | Session state | `Last-Event-ID` present | Buffer covers gap | Action | |---|---|---|---| | Active | No | n/a | Open stream at current head (fresh subscribe). Valid. | | Active | Yes, in-sequence | Yes | Replay from ID, then continue live. Valid resumption. | | Active | Yes, in-sequence | No (evicted) | **Fail: `400`.** Do not open a stream. | | Active | Yes, not in-sequence | n/a | **Fail: `400`.** Unknown resume point. | | Expired / terminated / unknown | Any | n/a | **Fail: `404`.** Client must re-initialize a new session. | The subtle rule: a `404` on an expired session is safe because the client knows to start over and can re-issue the original request. A `400` on an evicted buffer is safe because the client knows the in-flight operation's stream is unrecoverable and can decide to retry the operation idempotently or surface the gap. A `200` in either failure row is the bug. ## Operational Effect Consequences of getting this boundary wrong: - **Silent event loss presented as success.** The most dangerous outcome. Agents make decisions on an incomplete event history with no error signal. - **Duplicate side effects on naive retry.** If the client, on a correct `400`/`404`, blindly re-issues a non-idempotent tool call, the operation may run twice. The server-side contract must therefore pair the failure with enough information (session ID, last acknowledged event ID, operation correlation ID) for the client to retry idempotently or reconcile. - **Session-fixation style confusion.** Accepting a `Last-Event-ID` that belongs to a different session lets one client's resume point alias another's stream position. Reject out-of-sequence IDs even when they are numerically valid. - **Correct behavior under load:** when the buffer TTL is shorter than the client's reconnect window, expect a high rate of legitimate `400`s. That is a capacity signal (increase buffer retention or shorten client reconnect backoff), not an error to suppress by widening acceptance. The operational heuristic for agents: **treat any resumption response that does not begin at or before the requested `Last-Event-ID` as a protocol violation, and treat `200` responses to resume requests as trustworthy only if the server has demonstrably retained the gap.** When in doubt, prefer a hard failure over a plausible stream. ```python class StreamResumeError(RuntimeError): """Raised when an MCP HTTP-native stream resume request cannot be honored without risking silent event loss. Callers must not open a stream.""" def resume_stream(session, last_event_id): """Decide whether an SSE resume request may proceed. Returns the list of buffered events to replay (possibly empty if the gap is provably empty and the stream is still live). Raises StreamResumeError with an HTTP status hint otherwise. """ if session is None or session.state in ("expired", "terminated"): # Unknown or dead session: client must re-initialize. raise StreamResumeError( "unknown or expired Mcp-Session-Id; re-initialize session", status=404, ) if last_event_id is None: # Fresh subscribe at current head. Always valid. return [] if not session.owns_event_id(last_event_id): # ID is not part of this session's sequence. Never alias across sessions. raise StreamResumeError( f"Last-Event-ID {last_event_id!r} not in session event sequence", status=400, ) retained = session.retained_events_after(last_event_id) highest = session.highest_emitted_event_id() if highest is None or last_event_id == highest: # No events emitted after the resume point: gap is provably empty. return [] if retained is None: # Buffer evicted; server cannot prove the gap is empty. raise StreamResumeError( "event buffer evicted for resume point; gap cannot be guaranteed", status=400, ) if not retained: # Events exist after last_event_id but none are retained: gap lost. raise StreamResumeError( "events exist after Last-Event-ID but were not retained", status=400, ) # Verify contiguity: retained must begin at the first event after last_event_id. if retained[0].id != session.next_id_after(last_event_id): raise StreamResumeError( "retained events do not start at the requested resume point", status=400, ) return retained ```