How do I make Claude Code wait for an MCP task with `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`?

To make Claude Code wait for an MCP task instead of sending it to the background, set CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND to 1. Anthropic's changelog lists the variable in Claude Code 2.1.319, dated November 6, 2026. Without it, a long job on an MCP server hands control back to Claude right away, and the result arrives later.

This site is independent and not affiliated with Anthropic. We read the changelog and Anthropic's documentation on 2026-11-07. We did not run this variable, because it needs an MCP server that supports tasks. Nothing below is a hands-on result, and we show no sample output.

What an MCP task is

An MCP server is a tool connection that Claude can call. Most calls are short. An MCP task is different: Anthropic's MCP documentation describes it as a long job, such as a report export or a build, that the server runs itself.

The default behavior is to not block you. The same page says "Claude's tool call returns once the server accepts the job", so Claude keeps working while the job runs. The footer shows a count such as 1 MCP task, and Claude gets the result when the job ends.

What 2.1.319 changed

Anthropic's changelog has two lines for 2.1.319 that belong together. The first sets the default:

Added support for MCP tasks in the terminal: when an MCP server runs a tool call as a task, Claude Code moves it to the background right away and tells Claude the result when it finishes

The second adds the switch:

Added the CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND environment variable to make Claude Code wait for an MCP task inside its tool call instead of moving it to the background right away

Our reading is that waiting suits a job whose result the next step needs, such as an exported report that Claude must read before it writes a summary. Anthropic does not say this, so treat it as our judgment, not a documented use case.

Set it in settings.json

Anthropic's MCP page suggests putting these variables in the env block of settings.json. The same block holds this one:

{
  "env": {
    "CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND": "1"
  }
}

The fourth step is our reading of the documentation, not something we observed. If your footer still shows a task, one of the conditions in the last section probably applies.

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.

Subscribe

What the variable does not change

Anthropic's environment variables reference says the variable makes Claude wait "in an interactive session". It then adds a catch: while automatic backgrounding is on, it "still moves the call to the background after two minutes by default".

So there are two different switches:

Setting	What Claude does
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1	Waits for a task's result, but a call still moves to the background after two minutes while automatic backgrounding is on
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0	Waits for every MCP tool call until the call ends

The MCP documentation says a call moved after two minutes becomes "a plain background call rather than an MCP task". It does not survive exiting the session. A real MCP task on a remote server does.

Waiting also has an exit. The documentation says pressing Esc, or reaching the wall-clock limit or idle timeout, ends the call, and Claude Code asks the server to cancel the task.

When there is no MCP task to wait for

The variable only matters when a call would become an MCP task. The MCP documentation lists the conditions, and several are easy to miss:

• The server must support tasks and connect on a recent protocol revision.
• Calls from a subagent never become tasks.
• The VS Code extension and the desktop app do not have MCP tasks.
• A one-shot claude -p run doesn't get MCP tasks.

In those cases Claude Code treats the call as an ordinary tool call, and this variable changes nothing. Our API vs MCP vs CLI guide explains when an MCP server is the right connection in the first place, and our connectors guide covers the chat-app side.

Where this does not help

• We did not run it. We have no output to show and cannot confirm the waiting behavior.
• The docs and the changelog disagree on the version. The environment variables page says "Requires Claude Code v2.1.304 or later". The changelog lists the variable as added in 2.1.319. Using 2.1.319 or later satisfies both.
• Third-party providers are unclear. The MCP page says tasks are unavailable on providers such as Amazon Bedrock. The 2.1.319 changelog says MCP tasks now work in the terminal without feature-flag fetching, and names Bedrock, Vertex and Foundry. We cannot tell which is current.
• Waiting blocks you. While Claude waits, you wait too, up to the limits above.

The same changelog entry adds one more control: set CLAUDE_CODE_DISABLE_MCP_TASKS=1 to turn MCP tasks off. That is a bigger switch than this one, since no call becomes a task at all.

If you manage settings for a team, check where the variable lands. Our 2.1.305 notes cover an earlier MCP allowlist change that matters for managed setups.

Which Claude Code version adds CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND?

Anthropic's changelog lists it in Claude Code 2.1.319, dated November 6, 2026. The environment variables page says v2.1.304 or later. The two disagree, so update to 2.1.319 or later, then run claude --version to confirm.

Does CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND work in claude -p?

The environment variables page describes it for an interactive session. A one-shot claude -p run doesn't get MCP tasks. In an Agent SDK or stream-json session, setting it to 1 is one condition that stops calls becoming tasks.

How do I stop an MCP task that is running in the background?

Select the task in /tasks and press x, or ask Claude to stop it. Anthropic's MCP page says Claude Code stops following the task and asks the server to cancel it, though the server may still finish it. Pressing Esc does not stop a background task.

Sources (checked 2026-11-07)

• Claude Code changelog: the 2.1.319 entry (November 6, 2026).
• Environment variables: the CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND row.
• Connect Claude Code to tools via MCP: MCP tasks, automatic backgrounding and how to make Claude wait.
• Settings files and precedence: where the user settings file lives.
• Run Claude Code programmatically: what a non-interactive run does with MCP work.

We will mention it in the newsletter if Anthropic reconciles the version gap.