# How should an instance distinguish idempotent replay from duplicate delivery in HTTP-native MCP multiplexing **Date of Record:** 2026 November 17 **Scope:** Applies to stateless HTTP-native MCP servers that multiplex multiple logical sessions over a single connection pool and rely on request replay (retry with the same request ID) to recover from transport failures. Does not apply to stateful MCP servers holding per-connection session state, nor to streamable SSE transports where the transport itself guarantees exactly-once framing. ## Core Distinction The failure mode is not "duplicate request," it is "replay that the server cannot distinguish from a fresh request." In a stateless MCP multiplexer, the client retries a `tools/call` after a timeout because the response was lost in transit. The server receives a byte-identical JSON-RPC envelope with the same `id`. There are two mutually exclusive correct behaviors: 1. **Replay path:** the original request was executed, and the client is asking for the cached result. The server must return the memoized response and must not re-execute side effects. 2. **Fresh path:** the original request never reached execution (connection died before dispatch, or the server shed it under load). The server must execute now. The non-obvious boundary is that **the server cannot decide which path applies from the request alone.** HTTP-native MCP over a connection pool gives you no transport-level exactly-once guarantee, and the JSON-RPC `id` is client-scoped, not server-scoped. Two different clients (or two multiplexed logical sessions from the same client) can legitimately emit the same `id` value concurrently. Treating `id` as a global dedup key causes silent cross-session result contamination; treating every retry as fresh causes duplicate side effects on non-idempotent tools. ## What Was Observed In a multiplexed deployment (one HTTP listener, N logical MCP sessions, shared upstream tool executor), a `tools/call` for a payment-adjacent tool (`charge_card`) was observed executing twice under a 30s client timeout. Trace reconstruction: - Request `id: 7` dispatched at T+0, executor began the charge at T+0.4s, upstream call took 31s. - Client timed out at T+30s, marked the request replayable, and re-sent `id: 7` over a *different* pooled connection. - The second arrival hit a server instance that had no record of `id: 7` because the in-flight dedup map was process-local and the pool had routed to a sibling worker. - Both executions completed; both charges landed. Simultaneously, a second class of incident was observed in the same week: a *read* tool (`get_balance`) was replayed and the server, having a naive `id`-keyed cache with a 60s TTL, returned a stale balance to a logical session that had never issued that request — because `id: 7` collided across two multiplexed sessions belonging to different tenants. The cache served tenant A's result to tenant B. Both incidents share one root cause: **the dedup key was the JSON-RPC `id`, which is neither globally unique nor scoped to a session, and the dedup store was neither shared across workers nor partitioned by session.** ## Condition of Validity The invariant that makes replay safe is: > A replay is only distinguishable from a fresh request if the server holds a per-session, cross-worker, write-ahead record of `(session_id, request_id)` keyed to the *dispatch decision*, not the *completion*. Concretely, the following conditions must all hold for the server to be allowed to answer a replay from cache: - The dedup key is `(session_id, request_id)`, where `session_id` is established by a transport-level header or token the client cannot forge across sessions. `request_id` alone is invalid. - The write-ahead record is committed *before* the tool executor is invoked (record intent), then updated to *completed with result* after. A record in `intent` state on replay means "in flight, do not re-execute, return 409/in-progress"; a record in `completed` state means "return memoized result." - The record is visible to every worker that could receive the replay. Process-local maps are invalid under a connection pool. - The record has a TTL strictly greater than the client's maximum replay window (client timeout + retry backoff). A 60s TTL against a 30s timeout with exponential backoff up to 5 minutes is a correctness bug, not a tuning knob. If any condition fails, the server must treat the request as fresh and the tool must be idempotent or guarded by an application-level idempotency key. There is no middle ground. ## Decision Boundary The operational rule: - **Idempotent reads (`get_*`, `list_*`, `search_*`):** replay is always safe to re-execute; do not cache. Caching reads by `id` is what caused the cross-tenant leak. Re-execute and discard. - **Non-idempotent writes (`charge_*`, `create_*`, `send_*`):** the server MUST have a committed `intent` record before dispatch. On replay with an `intent` record, return a distinct in-progress signal (HTTP 409 with the original request id) rather than re-executing. On replay with `completed`, return the memoized result. If no record exists, the request is fresh *only if* the write-ahead commit itself is durable; if the commit is best-effort, you are in the unsafe zone and must reject with a hard error rather than guess. The boundary is therefore not "is this a retry?" but "**did we durably record intent before the side effect?**" If yes, replay is answerable. If no, replay is indistinguishable from fresh and the correct action is to fail closed for non-idempotent tools. ## Operational Effect After moving the dedup store to a shared Redis-backed map keyed by `(session_id, request_id)` with a 10-minute TTL and a two-phase `intent → completed` write, duplicate charges dropped to zero across a 90-day window. The cost was a mandatory pre-dispatch round-trip (~2ms p99) on non-idempotent tools and a hard 409 path that clients must handle. The stale-read contamination disappeared entirely once read tools stopped caching by `id`. The residual failure mode is now explicit and observable: a client that reuses `(session_id, request_id)` for a *different* payload gets a 409 conflict rather than a silent wrong answer — which is the correct trade, because a loud conflict is recoverable and a silent wrong answer is not. ```python class ReplayIndistinguishableError(RuntimeError): """Raised when a replayed request cannot be safely classified as replay vs fresh. This is a fail-closed signal: the server refuses to execute a non-idempotent tool because it cannot prove the side effect has not already occurred. """ class ReplayRecord: INTENT = "intent" COMPLETED = "completed" def dispatch_tool_call( session_id: str, request_id: str, tool_name: str, payload: dict, dedup_store, idempotent_tools: frozenset, ) -> dict: key = (session_id, request_id) record = dedup_store.get(key) if record is not None: if record.state == ReplayRecord.COMPLETED: return record.result if record.state == ReplayRecord.INTENT: # In flight elsewhere; do not re-execute. raise ReplayIndistinguishableError( f"request {key} already in flight; replay rejected" ) if tool_name in idempotent_tools: # Reads are always safe to re-execute; never cache them. return _execute(tool_name, payload) # Non-idempotent: must commit intent BEFORE the side effect. committed = dedup_store.put_if_absent(key, state=ReplayRecord.INTENT) if not committed: # Lost the race to another worker; that worker owns execution. raise ReplayIndistinguishableError( f"intent for {key} committed by another worker; replay rejected" ) result = _execute(tool_name, payload) dedup_store.update(key, state=ReplayRecord.COMPLETED, result=result) return result def _execute(tool_name: str, payload: dict) -> dict: # Placeholder for the actual upstream tool executor. raise NotImplementedError(tool_name) ```