<!-- MCP tool call timed out? Check the write before retrying · https://www.mcpdelta.com/guides/mcp-write-timeout · updated 2026-10-13 -->

> MCP tool call timed out? The change may still have happened. Check before you retry, see which calls are safe to repeat, and set the timeout.

[Delta MCP](https://www.mcpdelta.com/) [Guides](https://www.mcpdelta.com/guides)

Guide

# MCP tool call timed out? Check the write before retrying

Updated 13 October 20267 min read By the Delta MCP team

The short answer

When an MCP tool call times out, you can’t tell whether the change happened. Your AI may have lost the reply, not the work. Check before you retry: look in the tool for what it tried to make. Retry only if it is missing. Never retry a send on your own.

## Why doesn’t a timeout tell you whether the change happened?

Your AI asked a tool to make a change, then waited. No reply came, so your AI app stopped waiting and reported a failure. That label describes the wait, not the change. Retry a change that was already made and you get two tickets, two pages or two messages.

Developers call such a change a write. Three things may have happened.

What may have happened when an MCP tool call timed out, and what a retry does in each case
| What happened | Is the change in the tool? | If you retry |
| --- | --- | --- |
| The request never arrived. | No. | Right call: the change is made once. |
| The tool is still working. | Not yet. It shows up after your AI gave up. | The change is made twice, unless repeating it is harmless. |
| The tool finished and the reply got lost. | Yes. | The change is made twice, unless repeating it is harmless. |

The MCP specification expects this. A client should set a timeout on every request and, when it passes, cancel the request and stop waiting. A cancel is no guarantee. The server may ignore it when the work is done or can’t be stopped. It can also arrive after the reply was sent.

Stripe’s API guide says the same: after a connection fails, you may not know whether the request ran. It tells you to treat a server error as an unknown outcome too.

## What should you do after a timeout, in order?

Do these in order. The first two take a minute.

1.  **Stop the retry** Now
    
    Tell your AI not to repeat the call: _“Don’t retry. First check whether it was made.”_ A retry on its own is how a change gets made twice.
    
2.  **Look in the tool, not in the chat** 1 minute
    
    Open the tool itself: the Notion page, the GitHub issues, the folder. Search for the title or id you asked for. The chat only knows the call failed.
    
3.  **Read what you find** 2 minutes
    
    **Found and complete:** the change was made. Carry on and don’t repeat it.  
    **Found, half done:** finish the missing part with an update, not a new create.  
    **Not found:** it never arrived, or it is still running. Wait a minute and look again.
    
4.  **Retry once, and only a safe call** Then
    
    If it is still missing, retry once. The table below says which calls are safe to repeat. Before a send, look where it lands.
    
5.  **If it keeps timing out, fix the cause** After
    
    A call that always times out has a limit that is too short or a job that is too big. Raise the limit for that server, or ask for less per call.
    

## Which calls are safe to retry?

A call is safe to retry when doing it twice leaves the same result as doing it once. Reads qualify. Many changes don’t. The HTTP standard treats PUT (set a value) and DELETE as safe to repeat, and the rows below follow it. A tool’s own `idempotentHint` or description beats them.

Which kinds of MCP tool call are safe to retry after a timeout, and how to check first
| The call | Retry as it is? | Check first by |
| --- | --- | --- |
| Read: search, list, open | Yes. It changes nothing. | Nothing to check. |
| Set a value: a status, a title, a label | Usually. Setting the same value twice leaves the same result, as with an HTTP PUT. | Reading the field. If a person changed it since, a retry overwrites their edit. |
| Add to something: a comment, a row, a line | No. Twice adds it twice. | Opening the item and looking for your addition. |
| Create: a page, an issue, a file | No. A retry makes a second one. | Searching by the title or id you gave. Retry only if nothing matches. |
| Delete | Usually, when it names one exact item, as with an HTTP DELETE. Not “the latest”: the second call hits another item. | Looking for the item. Gone means done. |
| Send: a message, an e-mail, a notification | Never on your own. A send can’t be taken back. | Looking where it lands: the sent list, the channel, the other side. If you can’t tell, ask before you send again. |

## Can an idempotency key stop the duplicate?

Sometimes. An idempotency key is a unique label sent with a request. If the same label arrives twice, the service does the work once and repeats its first answer. It is built for a request that got no reply.

-   **How a key works at Stripe.** Its v1 API takes a key on `POST` requests. It saves the first result, even an error, and returns it again for a retry with the same key. It keeps keys for at least 24 hours. The same key with other parameters is rejected.
-   **What a retry must do.** Send the same key and the same parameters. Stripe says not to retry with a new key until you know the first outcome. A new key on each attempt gives no protection.
-   **What MCP gives you.** A `tools/call` request carries a tool name and its arguments. The specification’s schema defines no idempotency key for it. A tool can still take one as an argument of its own, so read its arguments.
-   **What a tool may declare.** `idempotentHint` says that calling the tool again with the same arguments has no additional effect. It is only a hint. The specification says clients should never base decisions on hints from servers they don’t trust.

So a key is a bonus, not a plan. When the tool offers none, the check above protects you.

## How do you change the MCP timeout?

A limit that is too short cuts off honest work. One that is too long leaves you waiting. Where you set it depends on your AI app. Here are Claude Code’s settings.

The Claude Code settings that limit an MCP tool call, what each one limits and its default
| Setting | What it limits | Default |
| --- | --- | --- |
| `MCP_TOOL_TIMEOUT` | How long one tool call may run, in milliseconds. | 100000000 ms, about 28 hours |
| `timeout` in `.mcp.json` | The same, for one server. It overrides the variable for that server. A hard limit: progress notifications don’t extend it. | The variable’s value |
| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | How long a call may stay silent, with no reply and no progress, before it aborts. 0 turns the check off. | 5 minutes for network servers, 30 minutes for stdio |
| `MCP_TIMEOUT` | Starting a server. For a remote server, it also counts in the per-request timer below. | 30000 ms, 30 seconds |
| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | When a call still running in the main conversation moves to a background task. 0 turns it off. Version 2.1.212 or later. | 120000 ms, 2 minutes |

**The 60-second default for remote servers.** A server reached over HTTP, SSE or as a claude.ai connector has a second timer. It runs on each request until the server’s first response byte. It lasts 60 seconds unless `MCP_TOOL_TIMEOUT`, the server’s `timeout` or `MCP_TIMEOUT` is set higher. Local stdio servers have no per-request timer.

To set it for one server, add `"timeout": 600000` to its entry in `.mcp.json`. That is ten minutes.

A slow call is not always a failed one. From version 2.1.212, Claude Code moves an MCP call in your main conversation to a background task after two minutes. It delivers the result when the call ends.

Cursor’s MCP documentation describes no timeout setting. The MCP specification names no number. It says SDKs should let you configure timeouts per request, and a client should always keep a maximum.

For work that takes minutes, a server can use MCP Tasks. It returns a handle at once, and the client polls for the result, even after reconnecting. Both sides must support it, and client support varies.

## What does Delta MCP do when an answer gets lost?

Delta MCP is a free app on your computer, between your AI and its tools. When a change gets no answer, it doesn’t guess and it doesn’t just retry. It reads the tool.

Before a change leaves, Delta MCP picks a read that can show whether it happened. That read is the object read again, or a list read again. When no answer comes, it runs that read at once. What the read shows decides:

What Delta MCP does when a change gets no answer, by what the read shows
| The read shows | Delta MCP |
| --- | --- |
| The change was made. | The task goes on, and the answer says it was checked. |
| The change was not made. | It sends the change once more, with the same arguments. It never does that on its own for a message or other send. For those, the answer says it was not seen, it may still show up, and the task stops. |
| Unclear, or nothing can be read to tell. | The answer says outcome unknown, and why. The task stops. Look at the tool before you make the change again. |

A tool called as it is can’t be rolled back by Delta MCP. If an earlier call succeeded, it stays made, and the answer lists it so your AI doesn’t repeat it. Each task that changes something is kept in Activity, with every change before and after.

[How a task is checked and applied](https://www.mcpdelta.com/docs/writing-a-task)

### Try Delta MCP on your own tasks

Free, two minutes to set up, and you can put everything back in one click.

[Download for Mac](https://www.mcpdelta.com/download)

Free · No account · Put everything back in one click

## Questions

### Is it safe to retry an MCP tool call after a timeout?

A read is. A change is not, until you have checked. The timeout only says no reply came: the tool may have made the change anyway. Look in the tool for it, and retry only if it is missing. Never retry a send on your own.

### Did my MCP write go through if the request timed out?

You can’t tell from the timeout. The request may never have arrived, the tool may still be working, or it finished and the reply was lost. Open the tool and look for the change.

### How do I increase the MCP tool timeout in Claude Code?

Set `MCP_TOOL_TIMEOUT` in milliseconds, or add a `timeout` field to the server’s entry in `.mcp.json`. For a remote server, set it above 60000 to lift the 60-second per-request timer. `MCP_TIMEOUT` is the startup wait, not the tool-call limit.

### How do I change the MCP timeout in Cursor?

Cursor’s MCP documentation describes no timeout setting. It says a failed call is marked as failed in the chat, and you can retry or check the logs. Check what the tool holds first.

### Does MCP have idempotency keys?

No. A tool call carries a tool name and arguments, and the specification’s schema defines no idempotency key for it. A tool can take a key of its own as an argument. It can also set `idempotentHint`, which is only a hint.

### What does Delta MCP do when a tool call gets no answer?

It reads the tool at once to see whether the change happened. Made: the task goes on. Not made: it sends the change once more. A message or other send is never sent again on its own. Unclear: the answer says outcome unknown and the task stops.

## Sources

1.  [**Model Context Protocol**, Cancellation](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation) Clients should set timeouts, cancel and stop waiting; a cancel may arrive after the work is done (revision 2026-07-28).
2.  [**Model Context Protocol**, Schema Reference](https://modelcontextprotocol.io/specification/2026-07-28/schema) A tool call carries a name and arguments, with no idempotency key; the idempotentHint annotation, and annotations are only hints (revision 2026-07-28).
3.  [**Model Context Protocol**, Tasks](https://modelcontextprotocol.io/extensions/tasks/overview) A durable handle for long operations, polled and retrieved after reconnecting; both sides must opt in.
4.  [**Claude Code**, Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) The per-server timeout, the 60-second per-request timer for remote servers, the idle window, the background move after two minutes.
5.  [**Claude Code**, Environment variables](https://code.claude.com/docs/en/env-vars) MCP\_TOOL\_TIMEOUT, MCP\_TIMEOUT, CLAUDE\_CODE\_MCP\_TOOL\_IDLE\_TIMEOUT and CLAUDE\_CODE\_MCP\_AUTO\_BACKGROUND\_MS, with defaults.
6.  [**Cursor**, Model Context Protocol (MCP)](https://cursor.com/docs/mcp) A failed MCP call is marked as failed in the chat; retry or check the logs; no timeout setting is described.
7.  [**Stripe**, Idempotent requests](https://docs.stripe.com/api/idempotent_requests) How an idempotency key works: the first result is saved and returned again; keys last at least 24 hours; other parameters are rejected.
8.  [**Stripe**, Advanced error handling](https://docs.stripe.com/error-low-level) After a connection fails you may not know whether the request ran; a server error is an unknown outcome; no new key before the outcome is known.
9.  [**IETF**, RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2) Idempotent methods (safe methods, PUT and DELETE), and not retrying a non-idempotent request unless you can tell the first was never applied.
10.  [**Delta MCP**, Writing a task](https://www.mcpdelta.com/docs/writing-a-task) What Delta MCP does when a change gets no answer: made, not made or outcome unknown; a send is not sent again on its own.
11.  [**Delta MCP**, Activity and Undo](https://www.mcpdelta.com/docs/activity-and-undo) Each task that changed something is kept in Activity, with every change before and after.

## Keep reading

-   [How to undo what an AI agent did in Notion, GitHub and files An AI agent changed or deleted something? See what changed, undo it in Notion, GitHub or your files, and what can never be taken back.](https://www.mcpdelta.com/guides/undo-ai-agent-changes)
-   [MCP vs CLI for AI agents: where the token bill comes from MCP or CLI for your AI agent? What each costs in tokens, what the measurements show, when a CLI wins, when MCP does, and where code beats both.](https://www.mcpdelta.com/guides/mcp-vs-cli)

![](https://www.mcpdelta.com/brand/app-icon.svg)

## Try Delta MCP on your own tasks

Free, two minutes to set up, and you can put everything back in one click.

[Download for Mac](https://www.mcpdelta.com/download) Also for [Windows](https://www.mcpdelta.com/download#windows) [Linux](https://www.mcpdelta.com/download#linux)

Free · No account · Apple chip or Intel