# Under what conditions must an instance treat MCP server-push notifications arriving during a resumed SSE stream as duplicates versus fresh events **Date of Record:** 2026 November 16 **Scope:** Applies to MCP servers using the HTTP-native transport (SSE-based streaming) where clients resume a broken stream via `Last-Event-ID` and the server interleaves server-initiated notifications (e.g., `notifications/tools/list_changed`, `notifications/resources/updated`, `notifications/message`) with responses to in-flight requests. Does not apply to stdio transport, nor to servers that do not support stream resumption and instead force a full re-initialize. ## Core Distinction The distinction is between **event-ID continuity** and **semantic continuity**. MCP's resumption contract is defined entirely by the SSE `id:` field: a client reconnecting with `Last-Event-ID: N` is promised all events with IDs strictly greater than `N`. This is a *transport-level* guarantee about the ordering of bytes on a stream. It says nothing about whether the *payloads* of those events are logically new. Server-push notifications are the failure surface because they are not request-scoped. A response to `tools/call` has an obvious correlation ID and a clear "already answered" state. A `notifications/tools/list_changed` has neither. When a server buffers notifications for replay across a reconnect, or when a notification is emitted by a fan-out mechanism that retries on disconnect, the same logical notification can legitimately appear under two different event IDs. The client sees two distinct SSE events (correct per the transport) that mean the same thing (one logical state change). ## What Was Observed A client connected to an MCP server, subscribed to `notifications/resources/updated` for a document, and began a long-running `resources/read` on the same document. The stream dropped mid-read (proxy idle timeout at 60s). The client reconnected with `Last-Event-ID` set to the last event it had processed. The server's resumption logic, implemented as a ring buffer keyed on event ID, replayed three buffered notifications that had been *emitted during the gap but already delivered before the drop* — because the server's buffer-append and its socket-write were not atomic, and the write had partially succeeded before the TCP reset. The client received: - `notifications/resources/updated` (event id 41) — first delivery, before drop - `notifications/resources/updated` (event id 41) — replayed, identical payload - `notifications/resources/updated` (event id 42) — genuinely new, emitted during the gap A naive client that de-duplicated on `id` handled 41 correctly. A client that de-duplicated on *payload hash* collapsed 41 and 42 into one, missing a real update. A client that de-duplicated on *semantic key* (resource URI) collapsed all three and refetched once — correct outcome, accidentally. A client that treated every received notification as fresh refetched three times, two of which were wasted and one of which raced with the in-flight `resources/read`. The dangerous case was the second: payload-hash dedup silently dropped a real state change because the server had coalesced two logical updates into identical notification bodies (both said "resource X changed"; the *content* of the change differed but the notification payload did not). ## Condition of Validity The invariant that makes a notification safe to treat as a duplicate is: **the notification is idempotent with respect to the client's reconciliation action, and the reconciliation action is a full re-read rather than an incremental patch.** Concretely, a replayed `notifications/resources/updated` for URI X is safe to collapse with any other such notification for X *only if* the client's response is "invalidate cache for X and refetch on next access" — because refetching once after N notifications yields the same final state as refetching N times. It is *not* safe to collapse if the client's response is "apply the diff carried in the notification," because two notifications with identical bodies may carry different diffs, and the transport gives you no way to distinguish a replay from a coalesced distinct event. The condition fails when: 1. The notification payload is not a pure function of the resulting state (i.e., it carries a delta rather than a snapshot reference). 2. The server coalesces multiple logical changes into one notification body during the gap (common in debounced implementations). 3. The client's reconciliation is incremental and order-sensitive. Under any of these, event-ID dedup is the *only* sound dedup, and payload dedup is a bug. ## Decision Boundary The decision the client must make on each received notification is: - **If** the notification is a *snapshot-reference* type (`resources/updated` with a URI, `tools/list_changed` with no payload) **and** the client reconciles by full refetch **then** dedup on event ID only; treat payload-identical events with distinct IDs as distinct triggers (harmless, idempotent). - **If** the notification carries a delta or a version vector **then** dedup on event ID only; never collapse on payload; require the server to have assigned monotonic IDs and trust only those. - **If** the client cannot establish that reconciliation is idempotent **then** it must not resume the stream at all — it must tear down the session and re-initialize, accepting the loss of in-flight request correlation, because a resumed stream with non-idempotent notifications is strictly worse than a fresh session. The boundary is therefore not "did I see this event before" but "is my reaction to this event a fixed point." If the reaction is a fixed point, event-ID dedup is sufficient and payload dedup is merely an optimization. If the reaction is not a fixed point, no dedup strategy is sound and resumption must be refused. ## Operational Effect Clients that adopt payload-hash dedup to "avoid redundant refetches" observe a specific failure signature: they miss updates that occur in rapid succession within the resumption gap, and the miss is silent — the client's cache is stale but no error is raised, and the staleness persists until an unrelated notification or a manual refresh. The bug reproduces only under stream drops concurrent with bursty server-side changes, which is precisely the condition resumption exists to handle, so it is under-tested. Servers that adopt ring-buffer replay without write-acknowledgement observe duplicate deliveries on partial writes; this is benign for idempotent clients and corrupting for delta clients. The mitigation on the server side is to advance the buffer pointer only after the socket write returns success, accepting that a crash between write and pointer-advance causes a duplicate rather than a loss — duplicates are the correct failure direction for this protocol. The operational rule: **resumption is a transport feature; idempotence is a semantic obligation the client must discharge before it may use resumption.** A client that has not proven its notification handler is a fixed point must treat `Last-Event-ID` as unusable and fall back to full re-initialization. ```python class NonIdempotentResumptionError(RuntimeError): """Raised when a client attempts to resume a stream whose notifications cannot be safely reconciled by a fixed-point handler.""" pass class NotificationHandler: def __init__(self, reconcile_is_fixed_point: bool): self._fixed_point = reconcile_is_fixed_point self._seen_event_ids: set[int] = set() def on_resume(self, last_event_id: int, buffered: list[dict]) -> None: if not self._fixed_point: # Resumption is unsafe: a replayed or coalesced notification # cannot be distinguished from a fresh one by payload alone, # and our reconciliation is order-sensitive / incremental. raise NonIdempotentResumptionError( f"refusing to resume from Last-Event-ID={last_event_id}: " f"notification handler is not a fixed point; " f"re-initialize the session instead" ) for ev in buffered: eid = ev["id"] if eid in self._seen_event_ids: continue # transport-level duplicate; safe to drop self._seen_event_ids.add(eid) self._reconcile(ev["payload"]) def _reconcile(self, payload: dict) -> None: # Fixed-point reconciliation: invalidate + refetch, not apply-delta. uri = payload.get("uri") if uri is None: raise NonIdempotentResumptionError( f"notification without snapshot-reference URI cannot be " f"reconciled idempotently: {payload!r}" ) self._invalidate(uri) def _invalidate(self, uri: str) -> None: ... ```