Claude Code MCP server timeout: the settings that fix it

A Claude Code MCP server timeout is one of four different limits, and each has its own fix. A server too slow to start needs MCP_TIMEOUT (30 seconds by default). A tool call that runs long needs a timeout on that server in .mcp.json. A call that goes quiet hits the idle window. And a result that is too big hits MAX_MCP_OUTPUT_TOKENS.

Everything below is from Anthropic's MCP page and CLI reference, read on 23 October 2026. Every value is in milliseconds unless it says tokens.

Which timeout did you hit?#

The server is slow to start: MCP_TIMEOUT#

A server launched with npx -y or uvx downloads its package the first time it runs, before it can answer Claude Code at all, and a remote server on a slow network is slow to answer too. Start Claude Code with a longer limit:

MCP_TIMEOUT=60000 claude

That's 60 seconds. With -p and --mcp-config, Claude Code waits for still-pending servers before the first turn, up to this same timeout. A server whose tool list is cached skips the wait and connects on first use.

To make it stick, export it from your shell profile. Our environment variables guide lists the others worth knowing.

If more time doesn't help and the server still shows as failed, time probably isn't the problem. Our guide to MCP servers that fail to connect shows how to read the real error with claude mcp get.

A tool call runs long: the per-server timeout#

A build, a database export or a crawl through an MCP server can run for many minutes. The wall-clock limit for a single tool call comes from MCP_TOOL_TIMEOUT, which Anthropic says defaults to about 28 hours when unset. To set it for one server only, add timeout to its entry in .mcp.json:

{
  "mcpServers": {
    "exporter": {
      "command": "npx",
      "args": ["-y", "some-export-server"],
      "timeout": 600000
    }
  }
}

600000 is ten minutes for that server, whatever MCP_TOOL_TIMEOUT says. Anthropic's page adds that a value below 1000 is ignored and that progress notifications from the server don't extend the limit, so a call still reporting progress at the tenth minute is cut off anyway.

A call goes quiet: the idle window#

Separate from the wall clock, Claude Code aborts a call that has sent no response and no progress notification for a while. The window is five minutes for HTTP, SSE, WebSocket and claude.ai connector servers, and 30 minutes for stdio servers. A server that reports progress keeps the window open; one that works in silence for six minutes is cut off at five.

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=1200000 claude

1200000 allows 20 silent minutes, and 0 turns the check off.

A long call also leaves the main conversation after two minutes: Claude Code moves it to a background task and the session keeps going. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS changes that two-minute threshold, and 0 turns it off.

The output is too big: MAX_MCP_OUTPUT_TOKENS#

This one isn't a timeout, though a cut result looks like a call that died. Claude Code warns when a tool's output passes 10,000 tokens and cuts it at 25,000 by default:

MAX_MCP_OUTPUT_TOKENS=50000 claude

The 10,000-token warning is fixed. And a successful text result longer than 50,000 characters is saved to a file whatever this variable says, unless the server raises that tool's own limit. Every result that does land in the conversation takes context, which our guide to MCP servers and context measures.

The server failed: reconnect and retry#

Claude Code already retries some failures. An HTTP or SSE server whose first connection fails with a 5xx, a refused connection or a timeout is tried up to three more times. A remote server that drops later is reconnected up to five times, starting at one second and doubling each time. A stdio server that fails its first connection is not retried on its own.

By hand:

1. claude mcp list in a shell prints one line per server, ending in ✔ Connected, ! Needs authentication or ✘ Failed to connect.
2. In a session, /mcp has a Reconnect entry on each server. /mcp reconnect all retries every failed one (Claude Code v2.1.284 or later in the terminal).
3. If it still fails, start Claude Code with claude --debug='mcp' and read what the server said.

One list of servers, one sign-in#

Timeouts are per machine: a server that starts fine on a fast desktop can time out on a laptop on hotel Wi-Fi, and each computer needs its own MCP_TIMEOUT export. Shuriken keeps one list of MCP servers for every project and account, hands it to Claude Code and Codex chats when they start, and you sign in to each server once, on any computer; Global MCPs shows how. For setting it up by hand, see MCP servers across all projects.