# Claude Code MCP server timeout: the settings that fix it > Claude Code MCP server timeout errors: the startup timeout for slow servers, a per-server limit for long tool calls, the idle window, and big output. Source: https://shuriken.sh/guides/claude-code-mcp-timeout Claude Code MCP server timeout errors: the startup timeout for slow servers, a per-server limit for long tool calls, the idle window, and big output. By Shuriken Updated 27 October 2026 4 min read **Contents** 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](https://code.claude.com/docs/en/mcp) and [CLI reference](https://code.claude.com/docs/en/cli-reference), read on 23 October 2026. Every value is in milliseconds unless it says tokens. ## Which timeout did you hit? # | What you see | The limit | Default | What changes it | | --- | --- | --- | --- | | The server shows as failed when the session starts | Startup | 30 s | MCP_TIMEOUT | | A long tool call is cut off at a fixed time | The tool call's wall clock | About 28 hours | MCP_TOOL_TIMEOUT , or timeout per server | | A call that stopped sending anything is aborted | Idle window | 5 min remote, 30 min stdio | CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | | A remote request gives up | Per-request timer (HTTP, SSE, connectors) | The largest of 60 s, the tool timeout and MCP_TIMEOUT | Raise either of the last two | | A warning about output size, or a cut result | Output limit | Warns at 10,000 tokens, caps at 25,000 | MAX_MCP_OUTPUT_TOKENS | ## 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: bash 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](https://shuriken.sh/guides/claude-code-environment-variables) 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](https://shuriken.sh/guides/claude-code-mcp-server-failed-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: 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. bash 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. Shuriken keeps one MCP list for all your agents, and an MCP sign-in follows you to every account and computer. [Download](https://shuriken.sh/download) ## 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: bash 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](https://shuriken.sh/guides/too-many-mcp-servers-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: - claude mcp list in a shell prints one line per server, ending in ✔ Connected, ! Needs authentication or ✘ Failed to connect. - 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). - 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](https://shuriken.sh/features/global-mcps) shows how. For setting it up by hand, see [MCP servers across all projects](https://shuriken.sh/guides/mcp-servers-across-all-projects). Try the free tool: [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) Share [X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-mcp-timeout&text=Claude%20Code%20MCP%20server%20timeout%3A%20the%20settings%20that%20fix%20it)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-mcp-timeout)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-mcp-timeout&t=Claude%20Code%20MCP%20server%20timeout%3A%20the%20settings%20that%20fix%20it)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-mcp-timeout&title=Claude%20Code%20MCP%20server%20timeout%3A%20the%20settings%20that%20fix%20it)[E-mail](mailto:?subject=Claude%20Code%20MCP%20server%20timeout%3A%20the%20settings%20that%20fix%20it&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-mcp-timeout) ## Sources - [Connect Claude Code to tools via MCP: timeouts, output limits, reconnecting (Claude Code docs)](https://code.claude.com/docs/en/mcp) (accessed 23 October 2026) - [CLI reference: --mcp-config and the MCP_TIMEOUT default (Claude Code docs)](https://code.claude.com/docs/en/cli-reference) (accessed 23 October 2026) ## Frequently asked questions **How do I increase the MCP timeout in Claude Code?** For a server that is slow to start, launch with MCP_TIMEOUT set in milliseconds, for example MCP_TIMEOUT=60000 claude. For a tool call that runs long, add a timeout field in milliseconds to that server's .mcp.json entry. **What is the default MCP startup timeout in Claude Code?** Thirty seconds, per Anthropic's CLI reference as read on 23 October 2026. MCP_TIMEOUT changes it. **Why does an MCP tool call stop after five minutes?** That is the idle window: a remote server that sends no response and no progress for five minutes is cut off (30 minutes for stdio servers). Set CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in milliseconds, or 0 to turn the check off. **How do I reconnect a failed MCP server without restarting Claude Code?** Open /mcp and choose Reconnect on the server, or run /mcp reconnect all to retry every failed server (v2.1.284 or later in the terminal). **Claude Code says the MCP output is too large. What do I change?** Raise MAX_MCP_OUTPUT_TOKENS, which caps a tool result at 25,000 tokens by default. The warning at 10,000 tokens is fixed and cannot be changed. Global MCPs One MCP list for every agent. Add an MCP server once, choose its projects and sign in once. Your Claude Code, Codex and Gemini CLI chats all get it. [Download](https://shuriken.sh/download) [Other platforms](https://shuriken.sh/download#main) ## Keep reading - [Claude Code across many projects: keep them apart: Guide 27 Oct 2026 6 min read Claude Code ties sessions, CLAUDE.md, settings and MCP servers to the folder you start it in. Run one session per project; put shared setup in user scope.](https://shuriken.sh/guides/claude-code-multiple-projects) - [Claude Code skills vs subagents vs MCP: which one to use: Guide 27 Oct 2026 6 min read Claude Code skills vs subagents: a skill is know-how in your chat, a subagent is work in its own context, MCP is a live outside system. One table to pick.](https://shuriken.sh/guides/claude-code-skills-vs-subagents) - [How to add an MCP server to Codex CLI: Guide 27 Oct 2026 4 min read Add an MCP server to Codex CLI with codex mcp add and the server's command, or write its table in config.toml. OAuth servers sign in with codex mcp login.](https://shuriken.sh/guides/codex-cli-mcp-servers) - [Codex MCP server failed to start or timed out: fixes: Guide 27 Oct 2026 6 min read In Codex, "MCP client failed to start" means the command or handshake broke; "timed out after N seconds" means a slow server: raise its startup timeout.](https://shuriken.sh/guides/codex-mcp-server-failed-to-start) - [Migrate Claude Code to a new computer, settings and all: Guide 27 Oct 2026 8 min read To migrate Claude Code to another computer, copy ~/.claude without the login file, keep project paths the same so old chats resume, and sign in again.](https://shuriken.sh/guides/migrate-claude-code-to-new-computer) - [Set up Shuriken in your first hour: Guide 27 Oct 2026 5 min read Set up Shuriken in order: sign in, add a project, add your accounts and keys, choose when chats switch, add MCP servers once, then your phone and servers.](https://shuriken.sh/guides/set-up-shuriken) - [Why Claude Code uses so many tokens: Guide 27 Oct 2026 7 min read Claude Code uses so many tokens because every request resends your whole context: CLAUDE.md, files read, tool output. Caching makes that cheaper, not free.](https://shuriken.sh/guides/why-claude-code-burns-tokens) - [Why is Claude Code slow? Causes and fixes: Guide 27 Oct 2026 5 min read Claude Code is slow for one of three reasons: the model, a huge conversation, or something on your machine. How to tell which, and the fix for each.](https://shuriken.sh/guides/why-is-claude-code-slow) ## Free tools - [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) - [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)