How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

You ask Claude Code to run a database export through an MCP server, the spinner starts, and twenty minutes later you are still not sure whether the call is working, hung, or already dead. How long until a Claude Code MCP tool call times out? The honest answer is “it depends on which of four timers fires first”, and until you know what those four timers are, every long MCP call is a guess. This post lays them out, with the exact environment variable for each, the defaults, and which one to change for which problem. Everything here is from the current Claude Code documentation on MCP and environment variables.

The four timers, in the order they usually fire

1. Server startup timeout (MCP_TIMEOUT): how long Claude Code waits for a server to come up before marking it failed. This one bites before any tool call happens.
2. Auto-backgrounding threshold (CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS, default two minutes): not a failure at all. A main-conversation tool call that is still running after this long moves to a background task so Claude can carry on.
3. Idle timeout (CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT, default five minutes for HTTP, SSE, WebSocket and claude.ai connector servers, thirty minutes for stdio servers): the call is aborted if the server sends no response and no progress notification for this long. This is the timer that ends most hung calls.
4. Hard wall-clock limit (MCP_TOOL_TIMEOUT, or a per-server timeout in .mcp.json): the absolute maximum for one tool call. With nothing set, the documented default is about 28 hours, which is to say it is not the timer you are waiting on.

So the practical answer for a server that has gone quiet is: a network server's call dies after five minutes of silence, a stdio server's after thirty, and both are moved to the background after two minutes while you wait. A server that keeps sending progress notifications can run for hours, up to the wall-clock limit.

Timer 1: server startup, MCP_TIMEOUT

MCP_TIMEOUT is a value in milliseconds that controls how long Claude Code waits for an MCP server to start. The documentation shows it as MCP_TIMEOUT=10000 claude for a ten-second window. If a server is slow to boot, for example a stdio server that installs dependencies on first run or a container that takes a while to answer, raise this and the “Failed to connect” status in claude mcp list often goes away. Run claude mcp get <name> to see the Issue: line with the HTTP status or error code before you assume it is a timeout.

One subtlety: for HTTP, SSE and claude.ai connector servers, MCP_TIMEOUT also feeds into the per-request timer described below, so raising it for startup reasons can lengthen how long each request waits for a first byte.

Timer 2: the two-minute move to the background

Since Claude Code v2.1.212, a tool call in the main conversation that is still running after CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS (default 120000, two minutes) becomes a background task. It shows up in /tasks, Claude keeps working on other things, and the result arrives when it arrives. The per-call limits below still apply while it runs. Calls from subagents, from IDE servers, and from non-interactive claude -p runs are not backgrounded unless you set CLAUDE_AUTO_BACKGROUND_TASKS=1. Set the threshold to 0 to turn automatic backgrounding off, and note that CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 turns it off as well. We covered the wider background-task machinery in the background tasks guide and in how to disable background tasks.

This is also why “it timed out” and “it went to the background” get confused: after two minutes the spinner changes and the conversation moves on, which looks like a failure if you were not expecting it. Check /tasks before assuming anything died.

Timer 3: the idle timeout that actually ends hung calls

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT (v2.1.187 or later) is the one to understand. It is an idle check, not a total: the call aborts only when the server has sent neither a response nor a progress notification for the whole window. The defaults are 300000 ms (five minutes) for network transports and 1800000 ms (thirty minutes) for stdio servers; before v2.1.203 stdio servers were exempt altogether. It applies to every server type except IDE servers and SDK in-process servers. Values below 1000 are raised to one second, and the value is capped at the effective wall-clock limit.

Two consequences for anyone writing or choosing MCP servers. First, a long-running tool that emits progress notifications will never hit the idle timeout, no matter how long it takes; a tool that goes silent for six minutes on an HTTP server will. If you own the server, send progress. Second, if you cannot change the server and its jobs are legitimately slow and silent, raise the idle window or set it to 0 to disable the check entirely:

# ten-minute idle window for every server
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=600000 claude

# disable the idle check (the wall-clock limit still applies)
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0 claude

Timer 4: the hard limit, MCP_TOOL_TIMEOUT and per-server timeout

MCP_TOOL_TIMEOUT is the wall-clock ceiling per tool call, in milliseconds, and progress notifications do not extend it. The documented default when it is unset is about 28 hours. You can also set it per server in .mcp.json, which overrides the global value for that server only:

{
  "mcpServers": {
    "warehouse": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "timeout": 600000
    }
  }
}

Per-server timeout has two rules worth knowing. Values below 1000 are ignored and fall through to MCP_TOOL_TIMEOUT. And a value of at least 1000 also raises that server's idle window to at least the same number, so a server with timeout: 600000 will not be aborted for idleness before ten minutes even if your global idle timeout is five. That makes the per-server field the right place to describe a known-slow server: one number, one server, both timers adjusted.

The per-request timer for HTTP and SSE servers

Remote servers have one more clock. For HTTP, SSE and claude.ai connector servers, each request has a per-request timer that covers the time to the server's first response byte. Its length is the greatest of 60 seconds, the tool timeout that applies to the server, and MCP_TIMEOUT; the 28-hour default of an unset MCP_TOOL_TIMEOUT does not count in that comparison. Stdio and WebSocket servers have no per-request timer. If a remote server takes ninety seconds before it starts streaming anything, you will see that request fail at sixty seconds unless one of those values is higher.

What happens after a timeout, and what does not

• An idle or wall-clock timeout returns an error for that tool call; Claude sees the error and usually tells you, or retries with different arguments. Timeouts on discovery requests (tools/list and friends) are not retried.
• A mid-session drop on a remote server triggers up to five reconnect attempts with exponential backoff from one second; after that you see MCP server "<name>" disconnected · open /mcp to reconnect, and /mcp reconnect all (v2.1.284 or later) brings everything back.
• Large results are a different failure: successful text results over 50,000 characters are written to a file rather than the conversation, HTTP responses over 16 MiB fail the request, and MAX_MCP_OUTPUT_TOKENS (default 25,000) caps what reaches the model. The post on MCP context usage covers that side.
• Killing a stdio server is fast: on macOS and Linux Claude Code sends SIGINT, then SIGTERM after 100 ms, then SIGKILL after a further 400 ms. A server that needs to flush state on shutdown has about half a second.

A sensible configuration for slow tools

# ~/.zshrc or your shell profile
export MCP_TIMEOUT=30000                      # 30 s to start a server
export CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=900000  # 15 min of silence allowed
# leave MCP_TOOL_TIMEOUT unset; set per-server timeouts in .mcp.json instead

Keep the global idle window modest, because it is the thing that rescues you from a genuinely hung server, and describe the exceptions per server with timeout. If you find yourself reaching for CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0, consider fixing the server to send progress instead; it is a small change and it makes the default behaviour correct for everyone who uses it.

Knowing when the long call finally finished

Once a call has been backgrounded it can finish ten minutes later, or forty, and you will not be watching. That is exactly the gap notifications close: a Stop or Notification hook fires when Claude needs you or is done, regardless of how many MCP timers ran in between. If you want to see which MCP tools were called and how long they took after the fact, the MCP audit post shows how to log every call with its duration.