# How should an instance distinguish MCP streamable-session resumption from server-initiated SSE reconnection **Date of Record:** 2026 November 17 **Scope:** Applies to MCP clients and servers using the HTTP-native "streamable" transport with `Mcp-Session-Id` correlation, resumable SSE via `Last-Event-ID`, and server-initiated reconnection hints. Does not apply to stdio transport, nor to stateless HTTP transports that do not carry a session identifier or an event-id ledger. ## Core Distinction There are two superficially identical client actions that occur over the same `GET /mcp` SSE channel and both involve re-opening a stream with a header: 1. **Session resumption** — the client is recovering *its own* prior event stream after a transport drop (TCP reset, proxy idle timeout, HTTP/2 GOAWAY). The client supplies `Mcp-Session-Id` plus `Last-Event-ID`, and the server replays events after that id. This is *client-initiated* and *idempotent with respect to the session*: the session must not be terminated by the drop, and the replay must be exactly-once in effect. 2. **Server-initiated reconnection** — the server has decided the current stream is unusable (e.g., it is draining a pod, it needs to shed a long-lived connection, or it is rotating an SSE writer) and signals the client to reconnect. This is *server-initiated* and *may* be accompanied by session-affecting semantics: a drain may imply the session is migrating to a different backend, and a naive client that treats this as ordinary resumption will replay against a backend that no longer holds the event ledger. The non-obvious boundary: **the two are indistinguishable from the client's HTTP view alone unless the server distinguishes them in-band.** Both arrive as "open a GET with `Last-Event-ID` set." A client that conflates them will either (a) silently lose events when the server has already discarded the ledger post-drain, or (b) duplicate side effects when the server replays an event the client already applied before the drop. ## What Was Observed In a streamable MCP deployment behind a connection-draining load balancer, the following sequence was observed repeatedly: - Client holds an SSE stream on `GET /mcp` with `Mcp-Session-Id: s-7f2a`. - The server's drain hook fires; the server sends a final `event: message` with a `retry` field and closes the stream *without* sending a `Last-Event-ID`-bearing error. - The client, seeing a clean EOF, treats it as a transport drop and reconnects with `Last-Event-ID: 1042`. - The server, now on a fresh pod, has no ledger for `s-7f2a` and — because the session id is opaque and not replicated — responds `404` to the `GET`. - The client interprets `404` as "session expired" and creates a *new* session, losing the in-flight tool-call correlation and re-issuing a `tools/call` that had already been executed server-side. The failure is not in any single step; it is in the boundary: **a server-initiated close that is not marked as such is indistinguishable from a transport-level drop, and the correct client response differs (migrate vs. resume).** A second observed variant: the server *did* send a `Last-Event-ID` on reconnect, but the ledger had been pruned to the last N events; the client's `Last-Event-ID` fell before the window, so the server replayed from the head of the window, silently re-delivering events the client had already applied. The client's dedup was keyed on event id, which was correct, but the *tool-call* dedup was keyed on request id, which the replayed events did not carry. ## Condition of Validity The distinction is only operationally valid when **all** of the following hold: - The server emits an explicit in-band signal distinguishing drain from drop (e.g., an SSE `event: reconnect` with a `reason` and a `resume` boolean, or an HTTP `Retry-After` plus a `Mcp-Session-Migrate` header). - The event ledger is either replicated across backends or the session id encodes the backend such that a reconnect to a different backend is detected before replay. - The client maintains a two-key dedup: event id (for SSE replay) *and* request id (for tool-call idempotency), because replay and idempotency are orthogonal. - The client treats `404` on `GET /mcp` as *session-unknown*, not *session-expired*, and does not auto-create a new session without first attempting a session-scoped `DELETE` and reconciling in-flight calls. If any of these is absent, the client cannot distinguish the two cases and must fall back to the conservative rule below. ## Decision Boundary The boundary is a single predicate evaluated at reconnect time: > **Is the close a server-initiated reconnection (session preserved, possibly migrated) or a transport drop (session preserved, same backend)?** - If **server-initiated with `resume: true`** → send `Last-Event-ID`, expect replay from the ledger, do *not* re-issue in-flight tool calls; reconcile by request id only if the ledger reports a gap. - If **server-initiated with `resume: false`** (drain/migrate) → do *not* assume ledger continuity; open a fresh `GET` with the session id, and if the server returns a migration hint, re-establish against the new backend and re-issue only calls whose request id is not in the acknowledged set. - If **transport drop** (no in-band signal, clean EOF or reset) → send `Last-Event-ID`, expect replay; if `404`, treat as session-unknown and escalate to reconciliation rather than auto-creating a new session. - If **ambiguous** (no signal, no ledger guarantee) → the conservative path: do not replay, do not re-issue; open a new stream, and reconcile in-flight calls against the server's `tools/call` status endpoint (or accept at-least-once and make the tool idempotent). The non-obvious part: **the ambiguous case is the common case** in deployments that have not yet added the in-band signal. The operational discipline is to treat ambiguity as "do not replay, reconcile out-of-band," not as "replay and hope." ## Operational Effect Conflating the two cases produces two distinct failure signatures: - **Silent event loss** — client resumes against a backend without the ledger, gets a 404, auto-creates a new session, and the in-flight tool call's result is never delivered. The session appears healthy; the call appears hung. - **Duplicate side effects** — client replays against a pruned ledger, re-applies events it already applied, and re-issues a non-idempotent tool call. The session appears healthy; the side effect appears twice. Both are invisible at the transport layer and only surface as application-level inconsistency. The mitigation is to make the distinction explicit in-band and to key idempotency on request id, not event id. Absent that, the client must adopt the conservative rule: **ambiguity means reconcile, not replay.** ```python from __future__ import annotations from dataclasses import dataclass from enum import Enum from typing import Optional class AmbiguousReconnectError(RuntimeError): """Raised when a reconnect cannot be classified as resume vs. migrate.""" class ReconnectKind(Enum): TRANSPORT_DROP = "transport_drop" SERVER_RESUME = "server_resume" SERVER_MIGRATE = "server_migrate" AMBIGUOUS = "ambiguous" @dataclass(frozen=True) class ReconnectSignal: kind: ReconnectKind last_event_id: Optional[str] ledger_continuity: bool # server guarantees replay from last_event_id migration_hint: Optional[str] def classify_reconnect( *, clean_eof: bool, in_band_reason: Optional[str], resume_flag: Optional[bool], ledger_continuity: bool, migration_hint: Optional[str], ) -> ReconnectSignal: """Classify a reconnect. Raises if the signal set is internally inconsistent.""" if in_band_reason is None: if clean_eof and not ledger_continuity: # No signal at all and no ledger guarantee: cannot distinguish. return ReconnectSignal( ReconnectKind.AMBIGUOUS, None, False, None ) if clean_eof: return ReconnectSignal( ReconnectKind.TRANSPORT_DROP, None, True, None ) raise AmbiguousReconnectError( "non-clean close with no in-band reason is unclassifiable" ) if resume_flag is True and not ledger_continuity: raise AmbiguousReconnectError( "server claims resume=true but offers no ledger continuity" ) if resume_flag is True: return ReconnectSignal( ReconnectKind.SERVER_RESUME, None, True, migration_hint ) if resume_flag is False: if migration_hint is None: raise AmbiguousReconnectError( "server-initiated non-resume close without migration hint" ) return ReconnectSignal( ReconnectKind.SERVER_MIGRATE, None, False, migration_hint ) raise AmbiguousReconnectError( f"unrecognized in-band reason: {in_band_reason!r}" ) def reconnect_action(signal: ReconnectSignal) -> str: """Return the conservative client action for a classified reconnect.""" if signal.kind is ReconnectKind.SERVER_RESUME: return "send Last-Event-ID; replay; reconcile by request id" if signal.kind is ReconnectKind.SERVER_MIGRATE: return "open fresh GET; re-issue only unacknowledged request ids" if signal.kind is ReconnectKind.TRANSPORT_DROP: return "send Last-Event-ID; on 404 escalate, do not auto-create session" raise AmbiguousReconnectError( "ambiguous reconnect: do not replay; reconcile out-of-band" ) ```