Claude Code MCP tool timeout: what to set for slow jobs

To change the MCP tool timeout in Claude Code, add a timeout field in milliseconds to that server's .mcp.json entry, or set the MCP_TOOL_TIMEOUT environment variable. For Sume's hosted MCP server you rarely need to: a jobs_wait call returns within 55 seconds, which fits under every default Claude Code documents.

The Claude Code facts come from its MCP documentation, read 2026-09-29. The 55-second figure comes from Sume's jobs and results page. A video render takes longer than one wait, so the agent waits in slices and the job keeps running on Sume in between.

Which timeouts does Claude Code apply to an MCP call?

There are several, and they answer different questions: how long the server may take to start, how long one call may run, how long it may stay silent, and when the session stops blocking on it.

How long does one Sume MCP call actually hold?

Not long. On the hosted MCP server, jobs_wait defaults to 50 seconds and is capped at 55. A larger timeout_seconds is clamped rather than rejected, and the response says so in wait_slice_clamped.

Sume's docs explain why: a wait is one HTTP request held open with nothing transferring, and an edge closes such a request eventually, so a ten-minute render is waited for by repeating the wait. When a slice ends first, the result is wait_slice_expired; the agent calls jobs_wait again with the same ids and never resubmits the paid create.

A 55-second slice is under the 60-second floor of the first-byte timer, well under the five-minute idle window, and far under the two-minute point where Claude Code backgrounds a call. That is why the defaults work for Sume without tuning.

Will Claude Code move a Sume call to a background task?

Only a call still running after two minutes moves to a background task, and only in the main conversation of an interactive session. A single jobs_wait slice ends before that, so a Sume wait does not trigger it. The video job itself is independent of this: it runs on Sume whether or not Claude Code is waiting on it.

Calls in non-interactive mode do not background a call unless CLAUDE_AUTO_BACKGROUND_TASKS is set to 1, per the same page.

When should I set a per-server timeout for Sume?

Set one only if a lower value is already in force. A per-server timeout below 55 seconds would cut a wait slice short at the wall-clock limit, and the call would fail even though the job is fine. Keep it above 55 seconds; the example below allows two minutes.

{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp",
      "timeout": 120000
    }
  }
}

What if a wait times out anyway?

A 524, 522, 523 or 525 on jobs_wait is a transport failure, never a job outcome, per Sume's docs. Re-issue jobs_wait on the same ids, or read jobs_status once. Do not resubmit the paid create.

For scripted fan-outs, script_run has its own timeout_seconds, 5 to 55, per MCP tools and gates. The same idea applies to Codex, where the default is different: see Codex MCP tool timeout.