Blog · · 9 min read
Fix MCP request timeouts without duplicate tool actions

An MCP request timeout is dangerous when the tool changes product state. The client can return -32001 while the server or an upstream API keeps working. The model sees a failed call and may try again, even though the first attempt might still commit. Raising the timeout only postpones that ambiguity. A reliable integration needs two clocks, a tested progress contract, durable execution for long work, cooperative cancellation, and an outcome-reconciliation gate before any retry. This guide shows how to build that path for MCP tools inside an existing product.
Diagnose which boundary timed out
Start by locating the timer. A request can expire in the agent host, MCP SDK, HTTP transport, reverse proxy, tool server, worker queue, or downstream product API. These timers do not share one meaning.
A client-side timeout means the caller stopped waiting. It does not prove that the server stopped. AgentCat's guide to MCP error -32001 describes this as a client deadline and notes that the server may still be working after the client rejects the call. Treat that guide as representative implementation coverage, then verify the exact SDK and host version you run.
Capture one diagnostic record per tool invocation:
{
"operation_id": "op_7f31",
"request_id": "mcp_184",
"tool": "issue_refund",
"effect_class": "payment.write",
"client_timeout_ms": 60000,
"idle_timeout_ms": 15000,
"business_deadline_at": "2026-09-14T14:05:00Z",
"last_progress_at": null,
"client_result": "timeout",
"server_cancel_ack": null,
"product_outcome": "unknown"
}
Log the configured timeout and the elapsed time at every boundary. Also record whether the client supplied a progress token, whether progress callbacks fired, whether the server observed disconnect or cancellation, and whether the downstream product recorded the operation ID. Without those fields, -32001 is only a symptom.
A direct report in the MCP Python SDK repository describes a tool exceeding ten seconds, followed by cancellation and disconnect behavior. It is an author report from a particular version, not a general guarantee. Its value is the reproducible failure shape: the client clock expires, cancellation arrives, and the server still needs explicit cleanup and outcome handling.
Use an idle lease and an absolute deadline
Most timeout fixes discuss one duration. Production tools need at least two.
Progress should renew an idle lease only when it advances, while an absolute business deadline never moves. The idle lease answers, "Has this request shown credible activity recently?" The absolute deadline answers, "Is this operation still worth completing for the product and user?"
The MCP progress specification requires progress tokens to identify active requests and requires the progress value to increase with each notification. It also allows the receiver to choose its reporting frequency and recommends rate limiting. Those rules support an implementation decision that is less common in generic timeout guidance: repeated, regressing, unknown-token, or post-completion heartbeats should not renew the idle lease.
Use a validator before touching the timer:
def accept_progress(run, message, now):
if message.token != run.progress_token:
return False
if run.state not in {"running", "cancelling"}:
return False
if message.value <= run.last_progress_value:
return False
if now >= run.business_deadline_at:
return False
run.last_progress_value = message.value
run.idle_expires_at = min(
now + run.idle_window,
run.business_deadline_at,
)
return True
The absolute deadline belongs to the product, not the model. Derive it from the user-facing workflow, such as a checkout reservation, approval expiry, support SLA, or report freshness requirement. Propagate the remaining budget rather than resetting the full duration at each model, tool, subagent, queue, and API hop.
If the idle lease expires, investigate or cancel. If the absolute deadline expires, stop accepting progress and move the operation toward cancellation or reconciliation. A busy loop that emits heartbeats must not keep authority, inventory, or a payment reservation alive forever.
Probe the client's actual progress behavior
MCP progress support does not prove that a specific client resets its timeout, so integrations need a capability probe. This distinction matters because MCP standardizes progress messages, while timeout-reset behavior can live in a client SDK or host configuration.
The specification says a requester can include a progress token and the receiver may send progress notifications. It does not promise that every host extends its wait window when one arrives. AgentCat documents a TypeScript SDK option that can reset a timer on progress and pair it with a maximum total timeout. That is useful implementation evidence, not a portable MCP guarantee.
A September 2026 coachemon issue asks whether the actual client timeout and progress-reset behavior were assumed rather than verified. The author reports a concrete risk: if a client abandons an acting tool and the model reissues it, the action can be applied twice. Preserve the report's status as practitioner evidence rather than presenting it as behavior of every client.
Run a startup or compatibility test for every supported host and SDK version:
- Call a read-only test tool with a duration just below the expected timeout.
- Call it again with no progress and confirm the observed expiry.
- Call it with valid monotonic progress at a known interval.
- Repeat with duplicate and regressing progress values.
- Confirm whether valid progress extends the idle window.
- Confirm that an absolute cap still terminates the call.
- Record the result in a client capability manifest.
A manifest entry should state the client name and version, default request window, per-call override support, progress callback support, progress-reset behavior, maximum-total-timeout support, cancellation transport, and durable-task support. Bind each run to the tested manifest version. If the host changes, expire the assumption and rerun the probe.
Do not simulate this with a write tool. The probe should be read-only, deterministic, and cheap. It measures waiting behavior, not whether a side effect can be rolled back.
Choose progress, a longer wait, or a durable task
Use the shortest execution shape that remains reliable.
| Work shape | Response pattern | Required protection |
|---|---|---|
| Usually finishes inside the client window | One synchronous call | Per-call deadline and typed failure |
| Sometimes slow but emits real progress | Synchronous call with progress | Idle lease, absolute deadline, validated progress |
| Reliably longer than the client window | Start and return a handle | Durable state, authorized status lookup, cancellation |
| Side effect can outlive the connection | Durable operation from the start | Stable operation ID and outcome reconciliation |
Microsoft's July 2026 long-running MCP tool sample states that MCP client tool-call timeouts are not standardized and may expire while work continues. Its sample waits for a short configurable budget, returns inline when work finishes quickly, and otherwise returns a durable workflow ID for polling. It also identifies a weakness in model-managed polling: the model can lose or invent the handle. Keep the handle in product-owned task state and expose it to the model through a typed tool result.
A result schema can make the next action explicit:
{
"operation_id": "op_7f31",
"state": "running",
"poll_after_seconds": 5,
"result": null,
"retry_allowed": false,
"next_action": "get_operation_status"
}
Use completed, failed, cancelled, and unknown as distinct terminal or reconciliation states. Do not overload failed to mean that the caller stopped waiting. For work measured in minutes, move to a durable task before the client timer becomes the execution boundary.
Treat a timed-out write as unknown
A timed-out side-effecting tool has an unknown outcome until the product reconciles it. This is the most important state in the design because it blocks the model's natural recovery behavior from becoming a duplicate write.
The MCP cancellation specification describes cancellation as best effort and requires both sides to handle races. A cancellation can arrive after a request completes, and a response can arrive after the caller decided to cancel. That means local cancellation is not a transaction rollback for an external payment, email, ticket update, or deployment.
When the client times out:
- Mark the local request
timed_outand the product outcomeunknown. - Send or observe the transport's cancellation signal when supported.
- Fence new execution attempts that use a different operation ID for the same intended effect.
- Query the product system by the original operation ID or an idempotency key.
- Accept a late response only if it maps to the same operation and current run.
- Return
completed,not_committed, orunknownto the model. - Permit retry only for
not_committed, using the same stable operation ID where the product contract supports it.
def retry_decision(operation):
outcome = reconcile(operation.operation_id)
if outcome == "committed":
return {"state": "completed", "retry_allowed": False}
if outcome == "not_committed":
return {"state": "failed", "retry_allowed": True}
return {"state": "unknown", "retry_allowed": False}
If the downstream system cannot query by operation ID, use a domain postcondition such as refund status, message delivery record, ticket version, or deployment revision. If neither is available, the tool is not safely retryable after an ambiguous timeout. Escalate instead of guessing.
Handle cancellation and late results explicitly
Cancellation has three separate facts: the caller requested it, the server observed it, and the external effect stopped. Record them separately.
Use states such as cancel_requested, cancel_observed, effect_stopped, effect_committed, and outcome_unknown. A server acknowledgement can prove that its handler observed cancellation, but not that an upstream API rolled back work already accepted. Likewise, a late success response can settle an unknown outcome without giving the stale request permission to mutate current run state again.
Fence late results with the operation ID, run ID, task revision, user and tenant, and accepted deadline. If a result belongs to an obsolete run revision, store it for reconciliation but do not inject it as a fresh model observation. This prevents a delayed response from reviving cancelled work or overriding a newer user decision.
Read-only tools can use a simpler policy. A late search result may be discarded and safely queried again if it has no external effect and freshness rules permit it. Write tools need the full reconciliation path.
Test the timeout contract under races
Happy-path latency tests are not enough. Build deterministic fixtures around every boundary:
- no progress before the idle lease expires;
- valid monotonic progress inside the idle window;
- repeated, regressing, unknown-token, and post-completion progress;
- valid progress continuing past the absolute deadline;
- client disconnect before server completion;
- cancellation before the external system accepts a write;
- cancellation after the external system accepts a write;
- late success after the client reports timeout;
- a second model call while the first outcome is unknown;
- a status lookup for an unknown or expired operation ID;
- client upgrade that changes timeout-reset behavior;
- durable task completion after user authority expires.
For every side-effecting fixture, assert that one operation ID produces at most one committed product effect. Assert that an unknown outcome never sets retry_allowed: true. Assert that repeated progress cannot keep the business deadline alive. Finally, compare the client capability manifest with observed traces so a host upgrade cannot silently invalidate the policy.
The tradeoff is extra product state. You need an operation ledger, capability manifest, status lookup, and reconciliation path. That cost is smaller than debugging duplicate refunds, emails, or deployments triggered because an SDK timeout was mislabeled as a failed operation.
Put the retry gate in front of one MCP write tool
Choose one side-effecting MCP tool that can exceed its client window. Add a stable operation ID, measure the real host timeout, validate progress against an idle lease and absolute deadline, and return unknown after ambiguous timeout or cancellation. Then run the race fixtures above. Do not let the model call the tool again until product-owned reconciliation proves the first attempt did not commit.