Stop Blocking on Slow MCP Calls: Claude Code Auto-Backgrounds Tool Calls That Run Long

Since Claude Code v2.1.212, any MCP tool call that runs longer than 2 minutes automatically moves to a background task — Claude gets the task ID, keeps working, and the result arrives as a task notification.

If you use Claude Code with MCP servers that call slow external systems — long-running database queries, external API calls, CI/CD checks, or custom tooling — you've likely hit this: a tool call starts, takes 3+ minutes, and your entire session is frozen until it finishes.

Since v2.1.212, this is on by default:

• An in-progress tool call that hasn't settled in 2 minutes moves to a background task automatically
• Claude receives the task ID immediately and keeps working
• When the call completes, it arrives as a task notification; Claude picks up where it left off
• Track progress (or stop the call) via /tasks

Configure the threshold

# Default: 120,000 ms (2 minutes)
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000

# Raise it for servers you know are slow (5 minutes):
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000

# Disable entirely (blocks on all tool calls as before v2.1.212):
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0

# Disable all background task features:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Add these to your shell profile or repo .env for per-project thresholds. The env var applies globally across all MCP servers.

Caveats

Per-call wall-clock limits still apply while a call runs in the background: the per-server timeout configured for that MCP server and CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT for calls that go silent. If those fire, the background task fails rather than hanging forever.

Background tasks don't survive session exit — closing Claude Code while a task is in progress cancels the call.

Sources: Connect Claude Code to tools via MCP — Claude Code Docs · Claude Code Changelog — Claude Code Docs · Auto-background long-running MCP tool calls — GitHub Issue #23611