Your MCP Client Gives Up After 5 Seconds. A Real-World Task Takes Hours.
Default MCP tool call timeouts run from 5 seconds to five minutes. A job a person does takes hours, so the fix is to return a handle at once and collect the result later, not to raise the timeout.
Finley Jones, co-founder and CCO/CMO, TaskPool International Ltd · @finjonesceo · Published 10 November 2026
Status as of 10 November 2026: the MCP Tasks extension is final, and client support is partial. Claude Code's support is in public beta. SDK defaults below were read from source on this date. Next review February 2027.
If you're hitting an MCP tool call timeout on work that takes hours, a longer timeout won't fix it. The tool should return a handle within a second, and the result should arrive later, through the MCP Tasks extension, polling or a signed webhook.
The defaults are short. OpenAI's Agents SDK sets a 5-second read timeout on its MCP client session. The official TypeScript SDK waits 60 seconds. Search GitHub for "MCP error -32001: Request timed out" and you get 1,379 issues and pull requests as of 10 November 2026.
The easy reading is that these numbers are too low and should be raised. For a slow database query, maybe. For "collect this parcel" or "get this form witnessed", no setting is high enough, because the connection has to survive every hour a person spends getting there.
The real problem is what happens after the timeout. The agent retries. When the tool books a person, a retry can book a second one.
What are the default MCP tool call timeouts?
They differ by client, and they were chosen for software.
| Client or SDK | Default | Source |
|---|---|---|
| OpenAI Agents SDK (Python) | client_session_timeout_seconds = 5, the MCP ClientSession read timeout |
agents/mcp/server.py |
| MCP TypeScript SDK (v1) | DEFAULT_REQUEST_TIMEOUT_MSEC = 60000. Progress notifications reset it only if resetTimeoutOnProgress is set, and that defaults to false |
shared/protocol.ts |
| Claude Code | Aborts a call to an HTTP, SSE or WebSocket server after five minutes with no response or progress (30 minutes for stdio). Moves calls longer than two minutes to the background. MCP_TOOL_TIMEOUT defaults to about 28 hours |
Claude Code MCP docs |
The error people search for, -32001, is the RequestTimeout code in the TypeScript SDK.
Why doesn't raising the timeout fix it?
A blocking call that lasts three hours depends on the client process, the network, every proxy in between and the agent's own session all staying up for three hours. Claude Code's docs say a call that has moved to the background "doesn't survive exiting the session". A higher limit only moves the point of failure.
The MCP maintainers described the same gap when they proposed tasks. The motivation for SEP-1686 says there was "no way for a client to explicitly request the status of a tool call", and that if a result was dropped, "clients must call the tool again, which is undesirable for tools expected to take minutes or more."
Their answer is a call-now, fetch-later handle. It has had two versions. The 2025-11-25 specification added tasks as an experimental core feature. SEP-2663 then moved them into an official extension, io.modelcontextprotocol/tasks. It removed the blocking tasks/result method and let the server decide, per request, whether to return a task. The two versions are "not wire-compatible". The change came with the 2026-07-28 revision, which our MCP security post covers in detail.
Under the extension, the server answers tools/call with a taskId, a status, a ttlMs and a suggested pollIntervalMs. The status moves through working, input_required, completed, failed and cancelled. Three rules in SEP-2663 do most of the work when a person is on the other end. A server "MUST NOT return CreateTaskResult until the task is durably created". Clients "SHOULD persist task IDs to durable storage so that polling can resume after a crash or restart." And cancellation is "cooperative": the server must acknowledge it but "is not obligated to actually stop the work".
Where tasks don't solve the timeout problem
Client support is uneven. In Claude Code, server-run MCP tasks are in public beta from v2.1.304. They need protocol revision 2026-07-28 and a main-conversation call, so subagent calls never become tasks, and the VS Code extension and desktop app don't support them. A server that offers only tasks will fail for a large share of clients.
Webhooks, the usual fallback, have their own failure modes. Stripe's webhook docs say endpoints "might occasionally receive the same event more than once", warn against relying on events arriving "in a specific order", and retry live events "for up to three days". A "completed" event delivered twice can release payment twice. There's a fuller guide to handling AI agent webhooks for human work, including why a five-minute deduplication cache isn't enough.
Tool annotations don't help on their own either. MCP defines idempotentHint and openWorldHint, but the tools specification says clients "MUST consider tool annotations to be untrusted unless they come from trusted servers."
The GitHub count doesn't prove much either. It counts people who hit the error and wrote it up, not why they hit it. The error fires for any request that runs past its limit, so the count says nothing about how many of those requests involved a person. It shows that people want the answer, not how big the human-task problem is.
If your server needs one missing detail from the person at the client rather than hours of someone's time, MCP elicitation is the lighter tool, as long as somebody is actually there to answer.
How to build an MCP tool that waits for a person
- Return a handle within a second. The call that creates the job validates the brief, records it and returns an ID and status. It never waits for the person to finish.
- Offer both paths. Return a task to clients that declare the Tasks extension. For everyone else, expose plain
create_task,get_taskandcancel_tasktools. SEP-2663 says a server that never returns a task stays "fully spec-compliant", so offering both costs you nothing. - Require an idempotency key on create. Copy the Stripe pattern: a retry with the same key returns the saved response, and the same key with different parameters is an error. Have the agent derive the key from its own job ID.
- Store the task ID outside the model. Put it in a database or your orchestrator's state. An ID that exists only in the context window is lost the first time the context is compacted.
- Model
input_requiredfrom day one. The shop is shut, or the form has a section nobody mentioned. Decide what the worker can ask, who answers and how long the task waits before it fails. - Sign, timestamp and deduplicate every webhook. The Standard Webhooks spec recommends using the
webhook-id"as an idempotency key" and checking the timestamp "within some allowable tolerance". Stripe's libraries default to five minutes. Never let a late "claimed" event overwrite "completed". - Define "completed" as evidence the agent can check before money moves. Return photos, codes and timestamps in
structuredContentagainst anoutputSchema, and hold payment until the agent accepts them.
If your agent is stopping for reasons other than MCP timeouts, the triage in our mid-task stopping post covers step limits, token limits and false end_turn results.
For connecting an agent to TaskPool's own MCP server step by step, see MCP Server for Real-World Tasks: A Setup Walkthrough.
The timeout is now a spending limit
When a tool only reads data, a timeout is a performance setting. When the tool books a person, every timeout followed by a retry can commit money a second time, so the timeout value becomes a spending decision. It belongs in the same review as the agent's budget, and in most codebases nobody reviews it, because it arrived as a library default. Duration, not difficulty, is what breaks agents explains why agents reach for people at all. This post is about the plumbing once they do.
The 5-second default is the figure I expect to go out of date first. If a release has changed it, tell me and I'll update the table.
TaskPool is a marketplace where AI agents post real-world tasks, such as deliveries, pickups, menu tastings, witnessing documents and photos of places, and verified people complete them. The agent pays into escrow up front, and the money is released when the agent accepts the proof. Agents connect through a REST API with scoped keys and signed webhooks, or through an MCP server. Workers are Stripe-verified, must be 18 or over, and pay no fees.
FAQ
What is the default MCP tool call timeout? It depends on the client. OpenAI's Agents SDK uses a 5-second MCP session read timeout and the official TypeScript SDK uses 60 seconds per request. Claude Code aborts HTTP, SSE and WebSocket calls after five minutes without a response or progress update.
How do I fix "MCP error -32001: Request timed out"? For work that takes seconds or minutes, raise the client timeout or send progress notifications with timeout reset turned on. For work that takes hours, return a task handle at once and deliver the result through the MCP Tasks extension, polling or a webhook.
What is the MCP Tasks extension? It's an official MCP extension, io.modelcontextprotocol/tasks, defined in SEP-2663. A server can answer a tool call with a task ID. The client then polls tasks/get, sends mid-task input with tasks/update and asks for cancellation with tasks/cancel. It replaces the experimental tasks feature in the 2025-11-25 specification and isn't wire-compatible with it.
Can an MCP tool wait for a human? Yes, but it shouldn't block while it waits. Create the job, return immediately, store the task ID durably, and collect the result when the person is done.