claude-code - 💡(How to fix) Fix [BUG] API Error: Stream idle timeout — fires during long-running MCP tool calls [2 comments, 2 participants]

Summary

API Error: Stream idle timeout - partial response received reliably triggers during autonomous agent runs that orchestrate many MCP tool calls, particularly when individual MCP calls take noticeable time to return. The stream goes idle while the model is waiting on an MCP response, the connection is killed mid-turn, and the partial output is unrecoverable.

Symptoms

• Error: API Error: Stream idle timeout - partial response received
• Fires mid-run, after several successful tool batches have already completed
• Most common during sequences that hit MCP servers with non-trivial response times (large file reads, transcript fetches, paginated listings across spaces, write-then-verify flows)
• "Try again" sometimes resumes, but often the agent restarts earlier work and hits the same wall again
• Anything in-flight at the time of the timeout (uncommitted edits, queued writes, follow-up reasoning) is lost

Workflow shape that triggers it

A long autonomous routine that:

• Dynamically loads MCP tool schemas via ToolSearch
• Issues parallel MCP read batches (vault/list/read, transcript fetches, community post listings, Slack lookups)
• Interleaves writes with read-back verification
• Runs for several minutes across a single turn

The error tends to fire when one MCP call is slow enough that the SSE stream sits silent past the idle threshold — even though the overall run is still making progress and the tool eventually returns.

Expected behavior

Either:

• The idle timeout should not treat a stream as "idle" while a tool call is in flight, OR
• The client should be able to recover/resume the partial response instead of aborting the entire turn and discarding work

Environment

• Claude Code (CLI + Web both reproduce)
• Model: Opus 4.7 (1M context)
• Workload: autonomous routine driving multiple MCP servers in parallel

Related

Likely related / duplicate of: #46987, #47252, #47385, #47698, #47763, #47841, #52507. Filing as a fresh signal that the bug is still actively reproducing and is specifically correlated with slow MCP tool execution rather than long generation.