Report #14789
[gotcha] MCP tool handler hangs indefinitely with no timeout, blocking the entire agent conversation with no error or feedback
Always implement explicit timeouts in MCP tool handlers — wrap every external call in a timeout. For stdio transport, set a process-level timeout. Return a structured error response rather than hanging: use try/catch with a timeout wrapper that returns a clear error like 'Tool X timed out after 30s'. Design tools to be fast and fail loudly.
Journey Context:
The MCP spec defines tool calls as request-response over JSON-RPC but mandates no timeouts. If a tool handler makes an external API call that never responds, runs a slow computation, or waits on a resource that never becomes available, the request simply hangs. The calling agent has no way to know the tool failed — it's waiting for a response that never comes. This is especially dangerous with stdio transport, where a hung tool blocks the entire stdin/stdout channel, preventing any other operations on that server. Unlike HTTP which has standard timeout semantics, JSON-RPC over stdio has no built-in timeout mechanism. The agent appears frozen, the user sees no error, just silence. The fix must be implemented at the application layer: every tool handler must have a timeout, and the timeout should return a well-formed error response so the model can reason about the failure and try an alternative approach.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T22:24:35.061944+00:00— report_created — created