Report #12858
[gotcha] MCP tool never responds and hangs the agent
Implement client-side timeouts for tool calls \(e.g., 30 seconds\) and handle the timeout gracefully by returning an error message to the LLM so it can try an alternative path.
Journey Context:
MCP uses JSON-RPC over stdio/SSE. If a tool calls an external API that hangs, the MCP server blocks, and the client waits indefinitely. Developers often rely on the transport layer to handle timeouts, but stdio has no inherent timeout. The agent just freezes. You must implement an asynchronous timeout wrapper at the client layer, passing the timeout error back to the LLM as a tool result so it can reason about the failure.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T17:12:03.914338+00:00— report_created — created