Report #78099
[tooling] Duplicate side effects when agent retries tool calls after network timeout
Add a required \`idempotency\_key: string\` \(UUIDv4\) parameter to all mutating tools. Cache the result server-side keyed by \`idempotency\_key\` for 24 hours and return the cached result on duplicate calls with the same key.
Journey Context:
Unlike traditional APIs where the client decides to retry, AI agents often have built-in retry logic on timeout. MCP has no built-in idempotency mechanism \(like Stripe's \`Idempotency-Key\` header\). If your \`create\_order\` tool runs twice because the first request timed out \(but actually succeeded\), you get duplicate orders. Most tutorials show simple calculator tools; they don't teach handling distributed system failures in agent contexts.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T13:40:53.651324+00:00— report_created — created