Describe the retry and backoff strategy a production MCP client should use for tools/call failures. What is the critical safety constraint that distinguishes safe retries from dangerous ones?
Retry transport-level JSON-RPC failures with exponential backoff and jitter, but never blindly retry a side-effecting tool; idempotency is the constraint that decides whether a retry is safe.
Imagine you mail a letter asking the bank to move $100, and you never get a reply. Did the bank get it or not? If you mail a second letter to be safe, you might move $200. That is the whole problem with retrying tool calls. Some requests are safe to resend, like asking 'what is my balance?', because asking twice changes nothing. Others, like 'send the money', are dangerous to resend, because the first one may have already worked. A careful client waits a bit longer between retries so it does not flood the bank, and it only resends the safe kind of letter. For the risky kind, it attaches a unique ticket number so the bank can spot a duplicate and ignore it.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Retrying a failed call feels like a solved problem until you do it inside an agent. A web client retries a flaky GET and nobody gets hurt. An MCP client retrying a tools/call can email a customer twice, charge a card twice, or delete a row that a prior attempt already deleted. The difference is that tool calls carry side effects, and the failure modes are ambiguous about whether those side effects happened.
The senior-level answer rests on one clean separation. There are two completely different kinds of failure in an MCP exchange, and they sit at different layers. Transport-level failures are about whether the JSON-RPC round trip completed. Tool-level failures are about whether the tool, once reached, succeeded at its job. Conflating them is the single most common production bug.
This deep dive builds the strategy from that separation: classify the failure, decide retryability, gate every retry on idempotency, bound the blast radius with backoff, keys, circuit breakers, and timeouts, and finally decide what the model is allowed to see.
Two layers of failure, not one
Every MCP tools/call can fail in two structurally different ways, and the protocol deliberately distinguishes them.
A transport-level failure means the JSON-RPC request never produced a clean, valid response. The socket dropped, the request timed out before a reply, or the server returned a JSON-RPC error object such as -32700 parse error, -32600 invalid request, or -32603 internal error. At this layer you often do not know whether the server even processed the request. The failure is about the channel, not about the work.
A tool-level failure is the opposite: the round trip completed perfectly. The server returned a normal result, but that result carries isError: true and an explanatory message. This is by design. MCP routes tool execution errors back inside a successful result rather than as protocol errors, precisely so the model can read and reason about them. A search that found nothing, a file that does not exist, an argument that failed validation downstream, all of these come back as isError results, not as broken transports.
The practical consequence: these two layers demand opposite handling. Transport failures may be retried; tool errors usually must not be. The reason is information. A transport failure leaves you uncertain whether the work happened, so a retry can recover a lost response. A tool error tells you precisely that the work was attempted and failed for a reason the inputs encode, so retrying the identical call just reproduces the same failure. Any retry policy that treats a dropped socket and an isError result the same way is broken from the start, either retrying calls that can never succeed or, worse, replaying side effects it should leave alone.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
| Aspect | Transport-level failure | Tool-level failure |
|---|---|---|
| Shape | JSON-RPC error object or dead socket | Normal result with isError: true |
| Round trip | Did not complete cleanly | Completed; tool reported a domain error |
| Retryable? | Transient ones yes, with backoff and jitter | Usually no; same inputs give same error |
| Outcome certainty | Ambiguous; side effect may have committed | Known; the tool definitely ran |
| Right move | Gate retry on idempotency, use a key if needed | Surface to the model, do not swallow |
Real products, models, and research that use this idea.
- Claude Code and Cursor wrap MCP tools/call dispatch with timeouts and bounded retries so a hung filesystem or Postgres server cannot freeze the whole agent session.
- AWS SDKs popularized exponential backoff with full jitter, the same recipe an MCP client applies to transient JSON-RPC transport failures.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you make a non-idempotent MCP tool safe to retry after an ambiguous timeout?
Client generates an idempotency key on attempt one and passes it through; the server dedupes by key and returns the original result on a replay, so a double commit is impossible.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Retrying every failed tools/call uniformly. A timeout on a side-effecting tool may have already succeeded, so a blind retry double-executes the side effect.
60 second bullets to scan on the way to the call.
Separating transport-level errors from tool-level isError results
Which JSON-RPC error codes are permanent versus transient
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.