MCP fetch timeout: the client settings that end a slow fetch

A fetch call hangs, then ends with "Request timed out" or MCP error -32001. Before you blame the site, find out whose clock ran out. Your MCP client runs its own timers, and they often end a slow fetch before the server has given up.

This post covers the timers in Claude Code and Codex CLI, and the config key for each. Checked against both clients' docs on 2026-11-12.

Whose deadline was it

The MCP spec asks every side to set timeouts on the requests it sends. When one runs out, the sender should send a cancellation notification and stop waiting. The spec also lets an implementation reset the clock when a progress notification arrives, but says a maximum timeout should apply regardless.

So a timeout in your client is usually your client's decision. The server gets a cancellation, and it may already be working on the page or done with it.

MCP error -32001: Request timed out is the clearest case. -32001 is RequestTimeout, raised by the MCP TypeScript SDK in the client when its deadline passes. That deadline defaults to 60 seconds. It is not a crash report from the server.

Claude Code: four timers

Claude Code applies several limits to an MCP tool call. For a remote (HTTP) fetch server, these matter:

1. First-byte timer. Each request to an HTTP, SSE or claude.ai connector server must get its first response byte in time. The limit is the greatest of 60 seconds, the server's tool timeout and MCP_TIMEOUT. A value below 60 seconds never shortens it.
2. Idle window. A call that gets no response and no progress notification for 5 minutes on an HTTP server (30 minutes on stdio) aborts with an error.
3. Wall-clock limit. The per-server timeout or MCP_TOOL_TIMEOUT. Unset, it is about 28 hours. Progress notifications do not extend the per-server timeout.
4. Startup. MCP_TIMEOUT bounds how long a server may take to start. The docs' example, MCP_TIMEOUT=10000 claude, sets 10 seconds.

For a single slow page, the first-byte timer is the one you hit first. The 28-hour default of an unset MCP_TOOL_TIMEOUT does not count toward it, so out of the box a remote fetch that sends nothing for 60 seconds ends there.

Raise the limit for one server

"timeout" in milliseconds on the server's entry is the narrowest fix. It overrides MCP_TOOL_TIMEOUT for that server only, and it feeds into the first-byte timer:

{
  "mcpServers": {
    "fetchmcp": {
      "type": "http",
      "url": "https://fetchmcp.net/mcp",
      "headers": { "Authorization": "Bearer ${FETCHMCP_API_KEY}" },
      "timeout": 120000
    }
  }
}

With 120000, the first-byte timer for this server becomes 2 minutes. Values below 1000 are ignored and fall through to MCP_TOOL_TIMEOUT. A per-server timeout of at least 1000 is also a floor on the idle window, so Claude Code never aborts that server for idleness sooner than that value.

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes the idle window for every server, in milliseconds. 0 turns the idle check off. It needs Claude Code v2.1.187 or later. Change it only if a server legitimately goes silent for more than 5 minutes; a fetch server rarely should.

Where the entry lives depends on its scope. The scope guide shows when that is .mcp.json and when it is your own config.

A long call is not a stuck session

A call in the main conversation that is still running after two minutes moves to a background task. That is not a timeout. The limits above still apply in the background. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS changes the threshold (default 120000); 0 turns backgrounding off. It needs v2.1.212 or later.

Codex CLI: two settings per server

Codex sets its limits per server in config.toml, in seconds:

• startup_timeout_sec: how long the server may take to start. Default 10.
• tool_timeout_sec: how long one tool call may run. Default 60.

[mcp_servers.fetchmcp]
url = "https://fetchmcp.net/mcp"
bearer_token_env_var = "FETCHMCP_API_KEY"
tool_timeout_sec = 120

bearer_token_env_var takes the name of the variable, not the key. A remote server has nothing to start locally, so startup_timeout_sec matters more for stdio servers launched through npx or uvx.

Before you raise anything

1. Retry once. A slow site is often slow only some of the time.
2. Test the URL outside the agent. The MCP Inspector CLI calls the tool directly from the terminal, so you can time one call on its own.
3. Raise one server's limit, not every server's. A per-server value leaves the other servers on their defaults.
4. Do not count a client timeout as a failed fetch. The client stopped waiting. The server may have finished the page anyway, so do not assume it was free or that nothing happened.

The fetch errors guide covers what to do when the site, not the client, is the slow part.

Try it with a real server

FetchMCP API's get_page_contents takes a URL, a format, a max_characters cap, compact or full output and a country. The client limits above decide how long you wait for it. Its docs say: "Every request fetches the page live; there is no cache." The config for each client is in the MCP docs.