The short version: on Claude Code v2.1.212 or later, any MCP tool call in the main conversation that is still running after two minutes is moved to a background task instead of freezing your session. Claude gets the task id right away, keeps working, and the result comes back as a task notification when the call settles (Claude Code docs).

If you only change one thing: know that CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS is the dial. Milliseconds. Raise it if two minutes is too twitchy, set it to 0 to keep MCP calls in the foreground the way they used to be.

The problem this fixes#

Before this shipped, a single slow MCP tool could hold your whole session hostage. Ask Claude to run a report against a big Postgres table, trigger a CI job, or call a deploy tool, and if that call took four minutes, you sat and watched a spinner for four minutes — every other thing you might have done in that session blocked behind one slow tool waiting out its timeout.

That is the exact annoyance the August build removes. A slow call no longer blocks you; it steps aside and finishes on its own.

What actually happens now#

An MCP tool call in the main conversation that is still running after two minutes moves to a background task. Concretely (Claude Code docs):

The move is automatic and needs no flag on a modern build. You mostly notice it by not noticing it: the shell stays responsive.

The one variable that controls the threshold#

The two-minute default is just a default. Set CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS (in milliseconds) to change it:

# Wait five minutes before backgrounding a slow MCP call
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000

# Keep MCP calls in the foreground — never auto-background (old behavior)
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0

Put it in your shell profile to make it stick across sessions, or export it inline for a one-off run. If you want no background tasks at all — not just for MCP — set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, which turns off automatic backgrounding along with every other background-task feature.

Backgrounding changes what blocks you — not how long a call may run#

This is the part people get wrong. Moving a call to the background does not give it unlimited runtime. The per-call limits still apply while it runs there (Claude Code docs):

A backgrounded call that blows past its timeout is still killed. You just were not frozen while it ran. If a tool routinely needs longer than its timeout, raise the timeout — backgrounding is not a substitute for it.

The calls that never move to the background#

Three cases stay in the foreground by design:

  1. Subagent calls. Claude Code backgrounds only main-conversation calls. A tool call made from inside a subagent runs to completion in place.
  2. Non-interactive / headless runs. In headless mode a call is not backgrounded unless you set CLAUDE_AUTO_BACKGROUND_TASKS=1 — a one-shot run can exit before the result comes back, so the default keeps the call in the foreground. If you run long headless jobs (CI, cron-driven agents), set that flag or your slow call may be cut short when the run ends.
  3. Calls waiting on an elicitation dialog. When a server has popped an elicitation prompt asking for your input, the call is not moved while the dialog is open — the server is blocked on you, not running slowly. The move is deferred until the dialog closes.

While you are in your MCP config, know the other cap that bites: Claude Code warns when an MCP tool's output exceeds 10,000 tokens and caps output at 25,000 tokens by default. Raise it with MAX_MCP_OUTPUT_TOKENS=50000 if a tool legitimately returns large results. Backgrounding governs how long a call blocks; this governs how much it can return — a slow, chatty tool can hit both.

What to do today#

This is one of a run of agent-ergonomics changes in the August Claude Code build; we tracked the rest, including sandbox credential masking and the free usage window, in this week's Founder's Wire. And if you are wiring MCP servers into agents in the first place, the stateless-core spec that landed on July 28 is the shape they now run in — start there, then come back and tune your timeouts.