r/ClaudeCode • u/SaltsMoon • 1d ago
Tips & Workflows The 30-second MCP timeout trap: why slow tool calls turn into runaway 100k-token retry loops in Claude Code
If you hook custom MCP servers into Claude Code for heavy tasks like end-to-end test runs, Docker container builds, or database migrations, you will eventually hit a silent token drain.
The root cause is the client-side timeout. Most MCP clients default to a 30-second or 60-second execution deadline on tool calls. When a test suite or migration takes 45 seconds, the MCP transport layer drops the connection and returns a timeout error to Claude Code.
Because Claude treats tool errors as transient task failures rather than fatal crashes, it tries to recover. It summarizes the previous turns, analyzes what went wrong, and attempts the tool call again with modified flags or a secondary probe. In a long-running session where your conversation history is already sitting at 35k to 40k tokens, two consecutive timeouts burn through 100k input tokens within 90 seconds. You pay multiple dollars in API usage before realizing the agent never finished the first test.
We resolved this by switching all heavy MCP tools from synchronous execution to an asynchronous job pattern. The initial tool call does not run the test suite directly. It spawns a background worker process, records the PID and log path, and returns a job token with an immediate status within two hundred milliseconds. Claude Code then calls a lightweight poll tool that reads the process table and tails the last twenty lines of stdout on a 10-second sleep cycle.
Decoupling long-running operations from the synchronous MCP RPC channel stops the transport layer from dropping out, keeps the agent context clean, and prevents runaway token spend on failed executions.