How Long Until a Claude MCP Tool Call Times Out?

My monitor showed a spinning cursor for four minutes straight. No error. No crash log. Just silence while a client's build pipeline sat frozen inside Claude Desktop, waiting on an MCP tool call that never returned. That night taught me more about timeout behavior than any documentation page has.

So how long until a Claude MCP tool call actually times out? If you build or maintain Model Context Protocol integrations, the honest answer depends on which Claude product you run, which transport your server uses, and whether you have touched a single config file since installing it.

The 60-Second MCP Wall: Why Claude Desktop Times Out

Thirty to sixty seconds is where most people first notice trouble. Anthropic does not publish that as a hard limit anywhere. It is simply the number that keeps showing up in bug reports once a tool call runs long enough to hit a second layer of timeout sitting underneath the one you can actually configure.

Understanding the Default Timeout Limit in Model Context Protocol

Does the Model Context Protocol specification set one official timeout number? It does not. 

The spec says implementations should time out outgoing requests, should enforce a hard ceiling regardless, and may reset the countdown when a progress notification arrives.

 That last part matters, because a tool reporting progress can run far longer than one that stays silent. Silence looks identical to a hang.

Claude Code documents two settings. MCP_TIMEOUT controls server startup and connection time. 

MCP_TOOL_TIMEOUT controls one tool call's execution time, and ships with a default so large, around 100 million milliseconds, close to 28 hours, that it is barely a limit at all.

Claude Desktop runs differently. Its MCP tool execution timeout is undocumented and cannot be changed through the same environment variables that work in Claude Code.

 Developers have measured it landing close to four minutes on Windows before the call drops with no visible error.

What Happens When a Tool Execution Crosses the Threshold

Nothing dramatic happens visually, and that is the real problem. The connection rarely throws a loud exception. 

The response stream closes, the socket drops, or Claude simply moves on without the data it asked for. If your tool was mid write to a database, that work keeps running even after Claude has given up on it.

That mismatch, a server still working after the client has walked away, is where real damage happens. 

Duplicate charges, half written files, and orphaned jobs usually trace back to a timeout on one side with no matching cancellation on the other.

Decoding GitHub and StackOverflow Insights on Timeout Errors

Anthropic's own issue tracker has the clearest picture of this, mostly because developers keep filing the same bug from different angles. The failure shows up across stdio, SSE, and streamable HTTP transports, on macOS, Windows, and Linux.

Why Claude Hangs Instead of Throwing a Clean Timeout Error

Why does Claude hang instead of throwing a clean timeout error the way a browser does? Many people expect something like an HTTP 408 when a request runs too long.

 That is not what happens. Claude does not return a literal 408 status for an MCP timeout. 

What you actually get is a socket hang up, an empty tool result, or a plain message that the request timed out, with nothing in the debug log pointing at which layer gave up first.

That ambiguity is the real time sink. I have burned afternoons chasing the wrong setting because the failure looked identical whether the server took too long to start, took too long to respond, or the connection quietly died mid stream.

The Trap of Infinite Tool Call Loops in Developer Workflows

A slower but equally common failure shows up when a tool call hangs, something retries automatically, and the retry hits a server still processing the first request. Now two jobs run where one should. 

Add a third retry and you have duplicate work competing for one resource, each copy slow enough to trigger another retry.

This is why any tool meant to run longer than a few seconds needs to be idempotent. Call it twice and it should land on the same end state, not two of everything.

Step-by-Step Guide to Fixing Claude MCP Timeout Issues

How to Increase the Timeout Limit in Your Local Configuration Files

Can you actually increase the Claude MCP timeout yourself? Yes, in Claude Code, through two files. The first is your project's .mcp.json, where a single server entry can carry its own timeout in milliseconds:

json

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "timeout": 600000
    }
  }
}

That setting overrides the global value for that one server only. The second file is ~/.claude/settings.json, where an env block sets the defaults everywhere else:

json

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

I tried the obvious shortcut first: a timeout key dropped straight into claude_desktop_config.json, assuming it would behave the same way it does in Code. It did nothing. 

That field is not part of Desktop's schema, and Desktop has no supported way to extend its MCP timeout. If a long running tool needs to live in Desktop, build it to finish fast or report progress, because you cannot configure your way around this one.

Adjusting Milliseconds and Request Parameters Safely

Every value here is in milliseconds, not seconds, and that mismatch is the single most common mistake I see. Set MCP_TOOL_TIMEOUT to 300 instead of 300000 and you get a timeout of three tenths of a second, so the server looks broken within moments of starting.

Apply the per-server field only where it is needed. Leaving the global MCP_TOOL_TIMEOUT enormous just to fix one slow tool hides genuine failures elsewhere in that session. 

Restart Claude Code, or reconnect the server through the /mcp command, after any change, since config files load at connection time, not continuously.

Moving Beyond Synchronous Limits: Handling Long-Running Tasks

Shifting to Background Execution and Polling Bash Commands

What is the best way to handle a Claude MCP tool call that runs longer than a minute? Stop waiting on it synchronously. 

Claude Code's Bash tool accepts a run_in_background flag, which fires a long command and hands back an id immediately instead of blocking. A companion tool, BashOutput, lets Claude check that id later, without ever holding one request open long enough to hit a timeout.

This is the same pattern backend engineers have used for two decades, now available inside the CLI with no extra infrastructure. Anything that might run past thirty seconds is a candidate for it instead of a blocking call.

Using Webhooks and Async Job Queues for Heavy Data Processing

For an MCP server you control, the same idea scales further. A tool call should accept the job, hand back a job id within milliseconds, and let the real work run on a queue, Redis or SQS or whatever the stack uses. 

When it finishes, a webhook notifies whatever is listening, or Claude polls a small status tool with the id it already has.

That one change removes timeouts from the conversation almost entirely, since no request stays open while heavy computation runs.

 The tool call that used to take four minutes now takes under a second, and the real work happens somewhere never subject to a conversational timeout at all.

Final Thoughts on Optimizing Claude MCP for Production Stability

Nobody builds an MCP server expecting to debug timeouts at midnight, yet almost everyone does eventually. 

The fix is rarely one giant number typed into a config file. It is matching the tool's actual runtime to the right pattern: quick calls stay synchronous, long calls get backgrounded, and anything genuinely heavy moves to a queue with its own status check.

Get that right once, and how long until a Claude MCP tool call times out stops mattering, because nothing you built is still waiting when the clock runs out.

A quick note on where the money fits. Freelancers and small agencies who maintain MCP integrations for clients often end up owning this exact problem, and a narrow, recurring fix like this one packages into real service tiers.

Service Tier	What You Fix	Typical Flat Price
Quick Diagnosis	Identify which timeout is firing and hand over one working fix	$75 to $150
Full Timeout Audit	Review every MCP server config, tune per server timeouts, confirm with live test calls	$300 to $600
Monthly Reliability Retainer	Ongoing monitoring plus timeout tuning each time a new tool gets added	$400 to $900 per month

Income from a niche fix like this tends to build slowly, then compound once referrals start.

Stage	Realistic Monthly Range	What Usually Changes
Month 1	$150 to $400	One or two diagnosis jobs picked up from forum posts or referrals
Month 3	$600 to $1,200	A couple of audits land plus a first retainer client
Month 6	$1,000 to $2,500	Two or three retainers running alongside occasional audit work

⚖️Disclaimer: This article is for informational and educational purposes only. The troubleshooting steps, configuration changes, and code examples above are general guidance, not a guarantee of outcome for any specific system. The Dollar Craft and its authors assume no liability for system downtime, data loss, or misconfiguration resulting from edits to local environment files, JSON configuration files, or API integrations. Back up your configuration and test changes in a non production environment before applying them anywhere that matters. The pricing and income figures above are illustrative estimates based on general freelance market patterns, not projections or financial advice, and actual results will vary by market, experience, and client base.