_runheed
Sign in

McpError: MCP error -32001: Request timed out

Node.js · updated 2026-11-11

Thrown by the MCP TypeScript SDK's Client when a request (initialize, tools/list, tools/call) gets no response within its timeout. The SDK default is 60 seconds (DEFAULT_REQUEST_TIMEOUT_MSEC), per request. SDK 1.x throws McpError with code -32001; the v2 client package (@modelcontextprotocol/client) throws SdkError: Request timed out with code REQUEST_TIMEOUT. The server may still be running the tool: the client just gave up on it. Clients built on other SDKs and hosts like Claude Code have their own limits on top.

McpError: MCP error -32001: Request timed out
    at McpError.fromError (node_modules/@modelcontextprotocol/sdk/dist/esm/types.js:2048:16)
    at Timeout.timeoutHandler (node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js:741:58)
    at listOnTimeout (node:internal/timers:585:17)
    at process.processTimers (node:internal/timers:521:7)
  code: -32001

Quick fix

Make long tools report progress, and have the client reset its timer on progress. With the TypeScript SDK, pass resetTimeoutOnProgress: true (and maxTotalTimeout as a hard cap) to callTool, and send notifications/progress from the tool. If you only control the host, raise its timeout. If the tool is just slow, make it faster or make it return a job id and finish in the background.

  1. Find out which request timed out: initialize and tools/list mean the server is slow to start; tools/call means one tool is slow.
  2. In the tool, send notifications/progress with the request's progressToken while it works.
  3. In your client, call callTool(params, undefined, { timeout, resetTimeoutOnProgress: true, maxTotalTimeout, onprogress }).
  4. In Claude Code, raise MCP_TIMEOUT for slow startup, and MCP_TOOL_TIMEOUT or a per-server "timeout" in .mcp.json for slow tools.
  5. For work that takes minutes, return a job id at once and add a second tool that reports the result.
typescript
// Server: report progress while the tool works.
server.registerTool('export_orders', { description: 'Export orders', inputSchema: {} }, async (_args, extra) => {
  const token = extra._meta?.progressToken;
  for (let page = 1; page <= pages; page++) {
    await exportPage(page);
    if (token !== undefined) {
      await extra.sendNotification({
        method: 'notifications/progress',
        params: { progressToken: token, progress: page, total: pages },
      });
    }
  }
  return { content: [{ type: 'text', text: 'Export finished' }] };
});

// Client (SDK 1.x): each progress notification restarts the 60 s timer; 10 minutes is the hard cap.
// With @modelcontextprotocol/client (v2) the options are callTool's second argument.
const result = await client.callTool({ name: 'export_orders', arguments: {} }, undefined, {
  resetTimeoutOnProgress: true,
  maxTotalTimeout: 10 * 60_000,
  onprogress: (p) => console.error(`progress ${p.progress}/${p.total}`),
});
Fix it with your coding agent

Paste this into Claude Code, Cursor or Codex in the project that throws it. The agent reads this guide in plain text and applies the fix that matches your stack.

prompttext
Read https://runheed.com/errors/mcp-error-32001-request-timed-out.md and fix this error in this project.

Why it happens

A tool takes longer than 60 seconds

A slow API, a big query or an export. Without progress notifications the client cannot tell slow from stuck.

The server never answers

The handler awaits a promise that never settles, or it is blocked by synchronous work, so no response is ever written.

Slow startup

The server does heavy work (downloads, migrations, npx installing the package) before it connects the transport, so initialize times out.

Progress without resetTimeoutOnProgress

Sending progress does nothing for the timeout unless the client opts in; the call still fails at 60 seconds.

Other fixes

  • The server keeps working after the client times out. Make long tools safe to run twice, because the user or agent will often retry.
  • For remote HTTP servers check proxy timeouts too: a proxy that cuts idle connections at 60 s gives a similar failure.

Same error, other wording

  • MCP error -32001: Request timed out
  • McpError: MCP error -32001: Request timed out (tools/call)
  • Error: MCP error -32001: Request timed out
  • SdkError: Request timed out (code REQUEST_TIMEOUT, SDK v2)

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and, when you set it, the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the MCP tool calls that time out with -32001, tell me which tool and how long they take, and add progress notifications or split the slow work so the call finishes in time.

7-day trial, then $29/moTry it in your agent on sample errorsSee the setupCancel any time from the billing portal

Setup for Node.js and Express or Vercel Functions, then have your agent fix and resolve it.

Building an MCP server? Track the errors your tools raise, in TypeScript or Python, so a failing tool shows up with its line instead of only in your users' client logs.

Related errors

More in MCP servers and clients

References: MCP specification: progress notifications, MCP TypeScript SDK: request options (timeout, resetTimeoutOnProgress, maxTotalTimeout), Claude Code docs: environment variables (MCP_TIMEOUT, MCP_TOOL_TIMEOUT)

Spotted a mistake? Email hello@greatwork.company. About Runheed.