Idempotencia

Las tools de creación y modificación aceptan un argumento idempotency_key. Se envía al endpoint como el encabezado X-Idempotency-Key que la API REST ya respeta — ver Idempotencia en la API.

{ "name": "finance_payables_create",
  "arguments": {
    "company_id": "…",
    "description": "Alquiler de noviembre",
    "amount": 4500,
    "due_date": "2026-11-10T00:00:00Z",
    "person": { "name": "Inmobiliaria Centro" },
    "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11"
  } }

Formato	String opaco, de 1 a 255 caracteres. Un UUID es la elección usual.
Repetición con el mismo cuerpo	Devuelve la respuesta original, sin ejecutar la operación de nuevo.
Repetición con cuerpo distinto	Conflicto (IDEMPOTENCY_KEY_REUSED).

Las tools que borran no aceptan el argumento: la ruta no lo lee, y borrar dos veces ya da el mismo resultado.

Por qué un agente lo necesita más que tu backend

Un cliente MCP que da timeout y reintenta, o un modelo que decide "no estoy seguro de que eso funcionó, lo hago de nuevo", es justo el patrón que crea el segundo título y el segundo movimiento. Tu backend tiene un bucle de reintentos que escribiste tú; el agente tiene un criterio.

Envía una clave siempre que la operación cree algo. Una clave nueva es un intento nuevo; para repetir con seguridad, repite la misma.

Las que mueven dinero: la clave es obligatoria

En estas cuatro la clave no es opcional — la tool rechaza la llamada sin ella, como la ruta:

Tool	Qué hace
finance_payables_send_to_bank	Envía el pago al banco por Kobana
finance_payables_cancel_dispatch	Cancela el envío al banco
finance_receivables_charge	Emite boleto o Pix al cliente
finance_receivables_charge_cancel	Cancela el cobro

Un envío duplicado es un pago duplicado, y un cobro duplicado es una deuda duplicada — ningún _delete lo deshace. Son también tools destructive: el servidor solo las ejecuta después de confirmar con la persona — vea Confirmación de tools destructivas.