# Where must an instance distinguish "resumed session" from "reconnected transport" in MCP HTTP-native streamable sessions **Date of Record:** 2026 November 17 **Scope:** Applies to MCP servers and clients using the HTTP-native transport where a session identifier is minted at `initialize` and a server-push SSE stream (or streamable request stream) is re-established after a transport drop, and the client presents a `Mcp-Session-Id` plus a resumption token (e.g., `Last-Event-ID`). Does not apply to stdio transports, nor to stateless HTTP deployments where no session identifier is issued. ## Core Distinction A **resumed session** means the server still holds the authoritative session state (initialized capabilities, negotiated protocol version, subscription set, in-flight server-push sequence) and can replay events strictly after the client's last acknowledged event ID. A **reconnected transport** means only the TCP/HTTP connection was re-established; the session may be gone (evicted, expired, or never existed on this instance) and the client's `Last-Event-ID` may point into a sequence the server cannot reconstruct. The non-obvious boundary: an HTTP 200 with an open SSE stream is *not* evidence of session resumption. A server that has lost the session can still accept the connection, emit `endpoint`/heartbeat frames, and look healthy to a naive client. The invariant that must be enforced is: **the server must not emit any event with a sequence number greater than the client's `Last-Event-ID` unless it can prove it holds the canonical session and has replayed the entire gap.** Conversely, the client must not treat a fresh stream as continuous with the old one unless the server explicitly signals replay completion. ## What Was Observed In a multi-replica deployment behind a load balancer with no session affinity, a client's SSE stream dropped mid-turn while the server had queued three server-push events (sequence 41, 42, 43). The client reconnected with `Mcp-Session-Id: s-7f3a` and `Last-Event-ID: 40`. The balancer routed to a different replica that had never seen `s-7f3a`. That replica returned HTTP 200, opened the stream, and immediately emitted a newly sequenced event numbered `1` from its local counter — a `notifications/tools/list_changed` push unrelated to the client's session. The client, seeing a live 200 stream, assumed continuity, discarded its pending request state, and reconciled against a tool list that belonged to no session it had ever initialized. No error was surfaced at any layer. The failure was silent and only detectable because a subsequent `tools/call` referenced a tool that the *original* session had negotiated but the new replica did not advertise. Two contributing conditions were confirmed empirically: (a) the transport layer treats "stream opened" as success independent of session validity, and (b) sequence numbers are per-stream, not per-session, so a fresh stream legitimately starts at 1 and cannot be distinguished from a replayed gap by number alone. ## Condition of Validity The resumption contract is valid only when all of the following hold: 1. The server can resolve `Mcp-Session-Id` to a session record whose event log retains every event after the client's `Last-Event-ID`. Retention is bounded; once the gap exceeds the retained window, resumption is impossible and must be refused, not silently restarted. 2. The session record is reachable from whichever replica terminates the new connection (shared store, sticky routing, or explicit redirect to the owning replica). 3. The server emits an explicit replay-completion signal (or the protocol's equivalent) before any *new* post-gap events, so the client can distinguish "replayed 41–43" from "here is a brand-new event 1." 4. Sequence numbers are scoped to the session, not the stream, so a reconnected-but-unresumed stream cannot masquerade as a continuation. If any condition fails, the correct behavior is a terminal session error (HTTP 404 for unknown session per the transport spec, or a protocol-level session-invalid error), forcing the client to re-`initialize`. Treating it as a successful reconnect is the failure. ## Decision Boundary The boundary is crossed at the moment the server decides what to do with a presented session ID it cannot fully honor. Three cases, three distinct actions: - **Session known, gap retained** → resume: replay the gap, then continue. Emit replay-complete marker. - **Session known, gap evicted** → refuse resumption but preserve identity: return a session error that tells the client to re-initialize *without* silently minting a new session under the old ID. - **Session unknown to this replica** → must not open a stream as if valid. Either redirect to the owner (with the session ID intact) or return 404. Opening a stream with a fresh sequence is the forbidden fourth case. The client-side mirror of the boundary: on reconnect, the client must require either a replay-complete signal or an explicit 404 before deciding whether its prior in-flight state is still meaningful. A bare 200 is insufficient. ## Operational Effect Enforcing this boundary converts a silent state-corruption failure into a loud, recoverable re-initialization. The cost is that naive clients see occasional re-initialize cycles after long disconnects or replica failover; the benefit is that no client ever reconciles against a session it did not establish. In the observed incident, adding session-scoped sequence numbers plus a 404-on-unknown-session rule eliminated the class entirely: reconnects either replayed correctly or failed fast, and the `tools/call` mismatch became impossible because the client could no longer mistake a foreign stream for its own. ```python class SessionResumptionError(RuntimeError): """Raised when a reconnect cannot be honored as a true session resumption.""" pass def resume_stream(session_id: str, last_event_id: int, store) -> "Stream": session = store.get_session(session_id) if session is None: # Do NOT open a fresh stream under an unknown session id. raise SessionResumptionError( f"unknown session {session_id!r}: client must re-initialize" ) if last_event_id > session.last_seq: raise SessionResumptionError( f"client claims event {last_event_id} but session {session_id!r} " f"only reached {session.last_seq}: client state is ahead of server" ) if not session.retains_after(last_event_id): raise SessionResumptionError( f"gap after event {last_event_id} evicted for session {session_id!r}: " f"cannot replay; re-initialize required" ) stream = session.open_replay_stream(after=last_event_id) stream.emit_replay_complete() return stream ```