La respuesta corta
Cuando una llamada a herramienta MCP da timeout, no puedes saber si el cambio se hizo. Tu IA pudo perder la respuesta, no el trabajo. Verifica antes de reintentar: busca en la herramienta lo que intentó crear. Reintenta solo si no aparece. Nunca reintentes un envío por tu cuenta.
En esta guía
¿Por qué un timeout no dice si el cambio se hizo?
Tu IA pidió a una herramienta que hiciera un cambio, y luego esperó. No llegó respuesta, así que tu app de IA dejó de esperar e informó de un fallo. Esa etiqueta describe la espera, no el cambio. Si repites un cambio que ya estaba hecho, tienes dos tickets, dos páginas o dos mensajes.
Los desarrolladores llaman escritura a un cambio así. Pueden haber pasado tres cosas.
| Qué pasó | ¿Está el cambio en la herramienta? | Si reintentas |
|---|---|---|
| La solicitud nunca llegó. | No. | Es lo correcto: el cambio se hace una vez. |
| La herramienta sigue trabajando. | Todavía no. Aparece después de que tu IA se rindió. | El cambio se hace dos veces, salvo que repetirlo no haga daño. |
| La herramienta terminó y la respuesta se perdió. | Sí. | El cambio se hace dos veces, salvo que repetirlo no haga daño. |
La especificación de MCP lo prevé. Un cliente debería fijar un timeout en cada solicitud y, cuando se cumple, cancelarla y dejar de esperar. Cancelar no garantiza nada: el servidor puede ignorarla cuando el trabajo ya está hecho o no se puede detener. La cancelación también puede llegar después de que se haya enviado la respuesta.
La guía de la API de Stripe dice lo mismo: tras un fallo de conexión, puede que no sepas si la solicitud se ejecutó. También indica tratar un error de servidor como un resultado desconocido.
¿Qué debes hacer después de un timeout, y en qué orden?
Hazlo en este orden. Los dos primeros llevan un minuto.
- Detén el reintentoAhora
Dile a tu IA que no repita la llamada: “Don’t retry. First check whether it was made.” Repetir sin más es la forma en que un cambio se hace dos veces.
- Mira en la herramienta, no en el chat1 minuto
Abre la herramienta misma: la página de Notion, los issues de GitHub, la carpeta. Busca el título o el identificador que pediste. El chat solo sabe que la llamada falló.
- Lee lo que encuentres2 minutos
Encontrado y completo: el cambio se hizo. Sigue y no lo repitas.
Encontrado a medias: termina la parte que falta con una actualización, no con una creación nueva.
No encontrado: nunca llegó, o sigue en marcha. Espera un minuto y vuelve a mirar. - Reintenta una vez, y solo una llamada seguraLuego
Si sigue sin aparecer, reintenta una vez. La tabla de abajo indica qué llamadas se pueden repetir. Antes de un envío, mira adónde llega.
- Si sigue dando timeout, arregla la causaDespués
Una llamada que siempre da timeout tiene un límite demasiado corto o un trabajo demasiado grande. Sube el límite de ese servidor, o pide menos en cada llamada.
¿Qué llamadas se pueden reintentar sin riesgo?
Una llamada es segura para reintentar cuando hacerla dos veces deja el mismo resultado que hacerla una vez. Las lecturas sí. Muchos cambios no. El estándar HTTP considera que PUT (fijar un valor) y DELETE se pueden repetir sin riesgo, y las filas de abajo lo siguen. Lo que declare la propia herramienta, en su idempotentHint o en su descripción, tiene prioridad sobre ellas.
| La llamada | ¿Reintentar tal cual? | Verificar antes con |
|---|---|---|
| Lectura: buscar, listar, abrir | Sí. No cambia nada. | Nada que verificar. |
| Fijar un valor: un estado, un título, una etiqueta | Normalmente. Fijar el mismo valor dos veces deja el mismo resultado, como con un PUT de HTTP. | Leer el campo. Si una persona lo cambió después, un reintento sobrescribe su edición. |
| Añadir a algo: un comentario, una fila, una línea | No. Dos veces lo añade dos veces. | Abrir el elemento y buscar tu añadido. |
| Crear: una página, un issue, un archivo | No. Un reintento crea una segunda. | Buscar por el título o el identificador que diste. Reintenta solo si no aparece nada. |
| Borrar | Normalmente, cuando nombra un elemento exacto, como con un DELETE de HTTP. No “el último”: la segunda llamada apunta a otro elemento. | Buscar el elemento. Si ya no está, está hecho. |
| Enviar: un mensaje, un correo, una notificación | Nunca por tu cuenta. Un envío no se puede deshacer. | Mirar adónde llega: la lista de enviados, el canal, el otro lado. Si no puedes saberlo, pregunta antes de volver a enviar. |
¿Una clave de idempotencia puede evitar el duplicado?
A veces. Una clave de idempotencia es una etiqueta única que se envía con una solicitud. Si la misma etiqueta llega dos veces, el servicio hace el trabajo una vez y repite su primera respuesta. Está pensada para una solicitud que no obtuvo respuesta.
- Cómo funciona una clave en Stripe. Su API v1 recibe una clave en las solicitudes
POST. Guarda el primer resultado, incluso un error, y lo devuelve de nuevo en un reintento con la misma clave. Conserva las claves al menos 24 horas. La misma clave con otros parámetros se rechaza. - Qué debe hacer un reintento. Envía la misma clave y los mismos parámetros. Stripe dice que no reintentes con una clave nueva hasta que sepas el resultado del primer intento. Una clave nueva en cada intento no da ninguna protección.
- Lo que te da MCP. Una solicitud
tools/calllleva el nombre de una herramienta y sus argumentos. El esquema de la especificación no define para ella ninguna clave de idempotencia. Una herramienta sí puede recibir una como argumento propio, así que lee sus argumentos. - Lo que puede declarar una herramienta.
idempotentHintindica que volver a llamar a la herramienta con los mismos argumentos no tiene efecto adicional. Es solo una pista. La especificación dice que los clientes nunca deben basar decisiones en pistas de servidores en los que no confían.
Así que una clave es un extra, no un plan. Cuando la herramienta no ofrece ninguna, la verificación de arriba te protege.
¿Cómo cambias el timeout de MCP?
Un límite demasiado corto corta trabajo que sí va bien. Uno demasiado largo te hace esperar. Dónde se fija depende de tu app de IA. Estos son los ajustes de Claude Code.
| Ajuste | Qué limita | Por defecto |
|---|---|---|
MCP_TOOL_TIMEOUT | Cuánto puede durar una llamada a herramienta, en milisegundos. | 100.000.000 ms, unas 28 horas |
timeout en .mcp.json | Lo mismo, para un solo servidor. Anula la variable en ese servidor. Es un límite estricto: las notificaciones de progreso no lo amplían. | El valor de la variable |
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | Cuánto puede quedarse en silencio una llamada, sin respuesta ni progreso, antes de abortar. 0 desactiva la comprobación. | 5 minutos para servidores de red, 30 minutos para stdio |
MCP_TIMEOUT | Arrancar un servidor. En un servidor remoto, también cuenta en el temporizador por solicitud de más abajo. | 30.000 ms, 30 segundos |
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS | Cuándo pasa a segundo plano una llamada que sigue en marcha en la conversación principal. 0 la desactiva. Versión 2.1.212 o posterior. | 120.000 ms, 2 minutos |
El valor por defecto de 60 segundos en los servidores remotos. Un servidor al que se llega por HTTP, SSE o como conector de claude.ai tiene un segundo temporizador. Se activa en cada solicitud, hasta el primer byte de respuesta del servidor. Dura 60 segundos, salvo que MCP_TOOL_TIMEOUT, el timeout del servidor o MCP_TIMEOUT lo fijen más alto. Los servidores stdio locales no tienen temporizador por solicitud.
Para fijarlo en un solo servidor, añade "timeout": 600000 a su entrada en .mcp.json. Son diez minutos.
Una llamada lenta no siempre es una fallida. Desde la versión 2.1.212, Claude Code pasa una llamada MCP de tu conversación principal a una tarea en segundo plano tras dos minutos. Entrega el resultado cuando la llamada termina.
La documentación MCP de Cursor no describe ningún ajuste de timeout. La especificación de MCP no fija ningún número. Dice que los SDK deberían permitir configurar los timeouts por solicitud, y que un cliente siempre debería mantener un máximo.
Para trabajos que tardan minutos, un servidor puede usar MCP Tasks. Devuelve un identificador de inmediato, y el cliente consulta el resultado, incluso después de reconectarse. Ambos lados tienen que soportarlo, y la compatibilidad de los clientes varía.
¿Qué hace Delta MCP cuando se pierde una respuesta?
Delta MCP es una app gratuita en tu computadora, entre tu IA y sus herramientas. Cuando un cambio no recibe respuesta, no adivina ni se limita a reintentar. Lee la herramienta.
Antes de que salga un cambio, Delta MCP elige una lectura que pueda mostrar si ocurrió. Esa lectura es volver a leer el objeto, o volver a leer una lista. Cuando no llega respuesta, hace esa lectura de inmediato. Lo que muestre la lectura decide:
| Lo que muestra la lectura | Delta MCP |
|---|---|
| El cambio se hizo. | La tarea sigue, y la respuesta dice que se comprobó. |
| El cambio no se hizo. | Envía el cambio una vez más, con los mismos argumentos. Nunca hace eso por sí solo con un mensaje u otro envío. En esos casos, la respuesta dice que no se ha visto, puede que aún aparezca, y la tarea se detiene. |
| No está claro, o no hay nada que leer para saberlo. | La respuesta dice “outcome unknown” y por qué. La tarea se detiene. Mira la herramienta antes de volver a hacer el cambio. |
Delta MCP no puede deshacer una herramienta que se llamó tal cual. Si una llamada anterior salió bien, queda hecha, y la respuesta la lista para que tu IA no la repita. Cada tarea que cambia algo se guarda en Activity, con cada cambio antes y después.
Cómo se comprueba y se aplica una tarea
Preguntas
¿Es seguro reintentar una llamada a herramienta MCP tras un timeout?
Una lectura sí. Un cambio no, hasta que lo hayas verificado. El timeout solo dice que no llegó respuesta: la herramienta pudo hacer el cambio de todos modos. Búscalo en la herramienta, y reintenta solo si no aparece. Nunca reintentes un envío por tu cuenta.
¿Llegó mi escritura en MCP si la solicitud dio timeout?
El timeout no lo dice. La solicitud pudo no llegar nunca, la herramienta pudo seguir trabajando, o terminó y la respuesta se perdió. Abre la herramienta y busca el cambio.
¿Cómo aumento el timeout de las herramientas MCP en Claude Code?
Fija MCP_TOOL_TIMEOUT en milisegundos, o añade un campo timeout a la entrada del servidor en .mcp.json. En un servidor remoto, ponlo por encima de 60.000 para quitar el temporizador de 60 segundos por solicitud. MCP_TIMEOUT es la espera del arranque, no el límite de la llamada a la herramienta.
¿Cómo cambio el timeout de MCP en Cursor?
La documentación MCP de Cursor no describe ningún ajuste de timeout. Dice que una llamada fallida se marca como fallida en el chat, y que puedes reintentar o revisar los logs. Antes, revisa qué tiene guardado la herramienta.
¿MCP tiene claves de idempotencia?
No. Una llamada a herramienta lleva un nombre y argumentos, y el esquema de la especificación no define para ella ninguna clave de idempotencia. Una herramienta puede recibir una clave propia como argumento. También puede fijar idempotentHint, que es solo una pista.
¿Qué hace Delta MCP cuando una llamada a herramienta no recibe respuesta?
Lee la herramienta de inmediato para ver si el cambio se hizo. Hecho: la tarea sigue. No hecho: envía el cambio una vez más. Un mensaje u otro envío nunca se vuelve a enviar por sí solo. No está claro: la respuesta dice “outcome unknown” y la tarea se detiene.
Fuentes
- Model Context Protocol, Cancellation Los clientes deben fijar timeouts, cancelar y dejar de esperar; una cancelación puede llegar después de que el trabajo esté hecho (revisión 2026-07-28).
- Model Context Protocol, Schema Reference Una llamada a herramienta lleva un nombre y argumentos, sin clave de idempotencia; la anotación idempotentHint, y las anotaciones son solo pistas (revisión 2026-07-28).
- Model Context Protocol, Tasks Un identificador duradero para operaciones largas, que se consulta y se recupera tras reconectarse; ambos lados deben optar por ello.
- Claude Code, Connect Claude Code to tools via MCP El timeout por servidor, el temporizador de 60 segundos por solicitud en servidores remotos, la ventana de inactividad, el paso a segundo plano tras dos minutos.
- Claude Code, Environment variables MCP_TOOL_TIMEOUT, MCP_TIMEOUT, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT y CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS, con sus valores por defecto.
- Cursor, Model Context Protocol (MCP) Una llamada MCP fallida se marca como fallida en el chat; reintentar o revisar los logs; no se describe ningún ajuste de timeout.
- Stripe, Idempotent requests Cómo funciona una clave de idempotencia: el primer resultado se guarda y se devuelve de nuevo; las claves duran al menos 24 horas; otros parámetros se rechazan.
- Stripe, Advanced error handling Tras un fallo de conexión puede que no sepas si la solicitud se ejecutó; un error de servidor es un resultado desconocido; ninguna clave nueva antes de conocer el resultado.
- IETF, RFC 9110: HTTP Semantics Los métodos idempotentes (seguros, PUT y DELETE), y no reintentar una solicitud no idempotente salvo que sepas que la primera no se aplicó.
- Delta MCP, Writing a task Lo que hace Delta MCP cuando un cambio no recibe respuesta: hecho, no hecho o resultado desconocido; un envío no se vuelve a enviar por sí solo.
- Delta MCP, Activity and Undo Cada tarea que cambió algo se guarda en Activity, con cada cambio antes y después.
Sigue leyendo
- Cómo deshacer los cambios de IA en Notion, GitHub y archivos¿Un agente de IA cambió o borró algo? Mira qué cambió, deshazlo en Notion, GitHub o tus archivos, y qué ya no tiene vuelta atrás.
- MCP vs CLI para agentes de IA: el origen del costo en tokens¿MCP o CLI para tu agente de IA? Qué cuesta cada uno en tokens, qué muestran las mediciones, cuándo gana la CLI, cuándo MCP y dónde el código supera a ambos.
