GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Todas las guías

· reAPI Team

Llamadas a herramientas MCP: por qué fallan tras cambiar de API

Sigue las llamadas a herramientas MCP desde el descubrimiento y la compatibilidad del modelo hasta la ejecución y los resultados devueltos. Diagnostica los fallos de migración de API antes de reintentar o enviar tareas de pago.

Llamadas a herramientas MCP: por qué fallan tras cambiar de API

El servidor MCP indica que está conectado. Aun así, el asistente responde con texto normal o dice que revisó una tarea sin mostrar ningún resultado. Si esto empezó después de cambiar las API de modelo, comprueba qué pasó por esa nueva conexión antes de volver a modificar el prompt.

Un servidor de herramientas conectado y un modelo capaz de solicitar herramientas son partes distintas de la aplicación. MCP define el descubrimiento y la invocación de herramientas. Después, el host debe exponer al modelo las herramientas adecuadas, ejecutar cualquier llamada permitida que solicite y devolver el resultado.[1][2] Que el primer paso tenga éxito no demuestra que también lo haya tenido el último.

Encuentra la herramienta en la lista que recibió el cliente

Empieza por una herramienta. Lee el resultado real de tools/list que recibió el cliente afectado, incluidas las páginas siguientes cuando corresponda. Conserva su nombre, descripción y esquema de entrada. El indicador de conexión no muestra si se descubrió esta herramienta concreta.

Si no aparece, comprueba el servidor seleccionado, el transporte compatible y la autenticación en el proceso que ejecuta el cliente. La especificación MCP actual permite que las herramientas disponibles varíen según la autorización proporcionada.[1] Por tanto, ver una herramienta no demuestra que el mismo llamador pueda ver todas las herramientas que ofrece ese servidor.

Para una conexión con reAPI, el servidor documentado usa Streamable HTTP remoto con un encabezado de autorización Bearer personalizado. Un cliente que solo ofrece inicio de sesión OAuth sin encabezados personalizados no puede conectarse con esa configuración.[3] Repetir una instrucción al modelo no puede aportar un transporte ni un mecanismo de credenciales que el cliente no tiene.

Durante la investigación, mantén separadas las credenciales del proveedor del modelo y las del servidor de herramientas. Pueden pertenecer a conexiones distintas. Cambiar una clave de API del modelo no arregla una credencial que falta en la conexión MCP, y cambiar la credencial MCP tampoco añade herramientas a una solicitud saliente al modelo. Registra identificadores de configuración seguros en vez de los secretos.

Compara el esquema descubierto con lo que ve el modelo

Usa como ejemplo esta herramienta ficticia de solo lectura. Busca una tarea existente por su ID. El fragmento ilustra una entrada de descubrimiento; no es una respuesta completa del protocolo ni una herramienta que hayamos desplegado:

{
  "name": "inspect_task_example",
  "description": "Look up the status of an existing task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string" }
    },
    "required": ["task_id"]
  }
}

Ahora inspecciona la solicitud serializada que se envió al modelo. Su formato de herramientas puede diferir del formato inputSchema de MCP, pero el nombre, la propiedad y el significado del campo obligatorio deben sobrevivir a la conversión. Si el host envía el nombre de la herramienta sin la propiedad task_id o la lista de campos obligatorios, el modelo ha recibido un contrato distinto.

Ese es un punto concreto donde reparar el adaptador. Un prompt más largo que le diga al modelo «usa la herramienta correctamente» no restablece el esquema que falta. Compara los dos objetos antes de añadir más instrucciones o cambiar otra vez de proveedor.

En este ejemplo, compara task_id en tres lugares: la propiedad descubierta, la propiedad que ve el modelo y los argumentos que el host envía después. Debe seguir designando el mismo valor de cadena obligatorio. Si un conversor lo cambia a id en un lugar, pero deja task_id en otro, ha introducido una discrepancia. Usa el contenedor de definición compatible con la API del modelo y conserva el nombre, el tipo y el estado obligatorio del campo.

Comprueba también si hay definiciones obsoletas. Una herramienta renombrada en el servidor puede conservar su nombre anterior en una lista del cliente almacenada en caché. Guarda la definición usada en la solicitud fallida para que la comparación refleje lo que recibió el modelo, y no el esquema más reciente de otra página de documentación.

¿El modelo pidió una herramienta o solo describió que la usaría?

Lee la estructura de la respuesta del modelo. El texto normal «Voy a revisar la tarea» no es una llamada estructurada a una herramienta. Una negativa, una respuesta normal, una llamada mal formada y una llamada válida requieren pasos distintos, aunque todas hayan llegado mediante respuestas HTTP correctas.

Si la solicitud incluía el esquema correcto pero no se devolvió ninguna llamada, revisa la compatibilidad del modelo, la configuración de elección de herramientas y la ruta utilizada. La selección automática de herramientas puede producir una respuesta normal; una opción que las desactive puede impedir que se seleccionen. La compatibilidad con valores más estrictos de elección de herramientas también varía según el modelo.[2] No trates cada ausencia como argumentos mal formados.

El enrutamiento es relevante cuando un intermediario elige un proveedor. OpenRouter documenta require_parameters para limitar las rutas a proveedores que admiten todos los parámetros solicitados. Sus preferencias predeterminadas de parámetros, incluidas las relativas a herramientas, no equivalen a un filtrado estricto.[4] Comprueba los modelos alternativos y la ruta que atendió la solicitud. No copies esa opción específica de un proveedor a otra API suponiendo que se comportará igual.

Si llegó una llamada estructurada, deja de depurar la selección y sigue esa llamada. El modelo ha solicitado una acción; la aplicación todavía tiene que ejecutarla. El tutorial de llamadas a herramientas de OpenRouter asigna explícitamente la ejecución al llamador, no al modelo.[2]

Sigue el mismo ID de llamada durante la ejecución y la devolución

Esta es la siguiente parte del ejemplo ficticio, con el formato de mensaje de Chat Completions. Los ID y el resultado son inventados. Son fragmentos de mensajes para inspeccionar, no un script que envíe una solicitud:

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_example_1",
        "type": "function",
        "function": {
          "name": "inspect_task_example",
          "arguments": "{\"task_id\":\"example_task_7\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example_1",
    "content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
  }
]

Entre esos dos mensajes, el host debe enviar la llamada permitida a la herramienta y recibir su resultado. Que una respuesta del modelo contenga call_example_1 no demuestra que se haya enviado. Busca el registro de ejecución correspondiente y el resultado del servidor.

Si la ejecución está esperando aprobación, conserva ese estado. Si el usuario la rechazó, el resultado es la operación rechazada; usar otra herramienta o reintentar no autoriza a eludir esa decisión. Si se aprobó pero nunca se envió, investiga la lógica de ejecución del host.

Comprueba también el nombre y los argumentos de la herramienta enviada frente a la llamada solicitada. En este ejemplo, la búsqueda debe recibir example_task_7; si el host reutiliza por error el ID de la tarea anterior, habrá ejecutado otra búsqueda, aunque el servidor devuelva un resultado válido. Guarda la correspondencia entre el ID de llamada del modelo, la invocación de la herramienta y el contenido devuelto. Así se puede detectar un resultado de otra tarea antes de que el modelo lo incorpore a una respuesta segura. Corrige esta correspondencia local sin cambiar el esquema de la herramienta de origen ni ampliar su acceso.

En las llamadas transmitidas en flujo, espera a que los argumentos estén completos. OpenRouter describe la recopilación de deltas por índice de llamada y su análisis cuando la cadena de argumentos está completa.[2] Un fragmento inicial que se detiene a mitad de task_id todavía no es JSON válido. Diferéncialo de una cadena de argumentos completa que sigue siendo inválida.

El segundo mensaje de arriba lleva el mismo ID de llamada que el primero. En el ciclo documentado de Chat Completions, al turno del asistente con la llamada a la herramienta le sigue un mensaje de resultado por cada llamada solicitada.[2] Si se devolvieron varias llamadas, conserva la identidad y el resultado de cada una. Enviar un resultado bajo todos los ID puede hacer que la conversación parezca completa mientras se asocian datos incorrectos a las acciones solicitadas.

Supón que la herramienta devolvió realmente processing, pero la siguiente solicitud al modelo omitió el mensaje de la herramienta. La ejecución tuvo éxito; el modelo nunca recibió el resultado. O supón que el host sustituyó el resultado por una cadena vacía durante la conversión. Cambiar el modelo dejaría esa misma información ausente en la conversación.

Compara el resultado real del servidor con la continuación saliente. Conserva el contenido y los errores pertinentes, no solo una marca de éxito en un registro del cliente. Evalúa la redacción final del modelo frente al resultado que recibió; afirmar que revisó la tarea no sustituye ese registro.

Mantén visibles los errores de las herramientas

MCP distingue los problemas del protocolo de los fallos de ejecución de las herramientas. Una herramienta desconocida o una solicitud de protocolo mal formada puede producir un error JSON-RPC. En cambio, un fallo de ejecución de una herramienta puede devolverse con isError: true.[1] Conserva esa distinción y el mensaje asociado al convertir el resultado para el modelo.

En la búsqueda del ejemplo, un error que indique que no se puede acceder a la tarea no debe convertirse en un estado de éxito vacío. Si el modelo solo recibe una cadena vacía, pierde la información necesaria para explicar el fallo o elegir el siguiente paso adecuado. Inspecciona la conversión antes de culpar a la respuesta final.

Una comprobación local útil consiste en pasar por el adaptador mensajes guardados o sintéticos: un resultado normal, un error de ejecución y dos llamadas con ID distintos. Verifica que se conserven el contenido, el significado del error y la identidad. Esto prueba cómo maneja el adaptador esos casos de prueba; no demuestra que un modelo remoto vaya a seleccionar correctamente la herramienta. Una evaluación con un modelo en directo puede generar cargos de inferencia aunque la herramienta elegida sea de solo lectura.

Haz que los dos resultados sintéticos sean claramente distintos y devuélvelos en el orden inverso al de las solicitudes. El host debe asociarlos por sus ID de llamada, no por el orden de llegada. Si los resultados de prueba son idénticos, el intercambio puede ocultar este error porque no produce diferencias visibles en la siguiente entrada del modelo.

Termina de comprobar la conexión antes de enviar una generación

En reAPI, empieza por las herramientas pertinentes que no envían tareas. La referencia de MCP indica que las operaciones de descubrimiento de modelos, recuperación de esquemas, estimación, estado de tareas y saldo no cobran créditos. submit_task es distinto: la llamada que crea una tarea se cobra por esa tarea.[3]

El servidor documentado no mantiene estado y acepta un mensaje JSON-RPC por solicitud HTTP, no matrices por lotes. Las entradas multimedia requieren URL públicas HTTP o HTTPS, no base64 ni URI de datos.[3] Si falla el paso de ejecución, comprueba esos requisitos reales de la interfaz; no envíes generaciones repetidas para probar la conexión.

Conserva el ID de tarea devuelto y consulta esa tarea existente. reAPI documenta que el envío de tareas no es idempotente: repetir una solicitud de creación puede generar otra tarea facturable.[3] Si se pierde la respuesta del envío, realiza una comprobación de aceptación, en lugar de suponer que no ocurrió nada.

Para la búsqueda ficticia, la comparación de migración termina cuando puedes mostrar dónde difieren por primera vez los mensajes: en el descubrimiento, la definición que ve el modelo, la llamada estructurada, la ejecución o el resultado devuelto. Corrige esa diferencia concreta y repite la misma comprobación inocua. Guarda juntos el servidor, el modelo, la versión del cliente y la llamada registrada para que la siguiente persona pueda ver qué se verificó sin depender de un indicador de conexión.

Referencias

  1. Model Context Protocol, Tools specification, revision 2026-07-28. Consultado el 16 de noviembre de 2026. Las versiones del protocolo y las implementaciones del servidor pueden variar.
  2. OpenRouter, «Tool Calling Across Any Model: Write the Loop Once, Swap the Model String», tutorial oficial, actualizado el 24 de septiembre de 2026. Consultado el 16 de noviembre de 2026.
  3. reAPI, MCP Server documentation. Revisado el 16 de noviembre de 2026. Para esta guía no se realizó ninguna generación en directo ni prueba de compatibilidad del cliente.
  4. OpenRouter, «Provider Routing», documentación oficial, secciones «Requiring Providers to Support All Parameters» y «Default parameter preferences». Consultado el 16 de noviembre de 2026.
Todas las guías