Goro

Para agentes de IA: MCP

Añade Goro a Claude, Cursor o cualquier cliente MCP como conector, y tu agente obtiene todo el catálogo como ocho herramientas.

Goro ejecuta un servidor MCP remoto. Añade una URL a tu cliente y el agente obtiene ocho herramientas que alcanzan todo el catálogo, con el mismo saldo y los mismos precios que la API HTTP.

https://mcp.usegoro.ai/mcp

1. Añade el conector

En Claude, Cursor o cualquier cliente MCP que admita servidores remotos, añade un conector personalizado con la URL anterior. El cliente se encarga del resto: se registra a sí mismo, abre la pantalla de consentimiento de Goro en un navegador y almacena el token que recibe a cambio.

El transporte es HTTP Streamable. El servidor no tiene estado por solicitud, por lo que no hay sesión que mantener activa ni nada que reconectar.

2. Autorízalo

La pantalla de consentimiento solicita una clave de API de Goro, la goro_live_ de app.usegoro.ai. Esa clave identifica qué espacio de trabajo y saldo gastará el conector. Pégala una vez, aprueba y el cliente quedará conectado.

Existen dos ámbitos, y un cliente que no solicite una concesión más restringida obtiene ambos:

Ámbito	Concede
tools:read	discover_tools, inspect_tool, create_upload, get_run, wallet_balance, remember_tool_choice, forget_tool_choice
tools:run	run_tool

Los tokens de acceso duran una hora y el cliente los renueva silenciosamente. Los tokens de renovación duran 30 días y rotan en cada uso.

Nota

¿Estás creando el cliente tú mismo en lugar de usar uno existente? El flujo OAuth está documentado de principio a fin en la guía rápida de OAuth.

Nota

Conectarse no significa que el espacio de trabajo pueda ejecutar herramientas todavía. discover_tools, inspect_tool y wallet_balance funcionan de inmediato. run_tool y create_upload necesitan un plan activo, Build o Scale, y responden subscription_required hasta que el espacio de trabajo tenga uno. Elige un plan en app.usegoro.ai/billing.

3. Las ocho herramientas

Herramienta	Ámbito	Cuándo la llama el agente
discover_tools	tools:read	Primero, siempre que la tarea necesite datos en vivo o externos y el slug exacto sea desconocido
inspect_tool	tools:read	Antes de ejecutar una herramienta cuya forma de entrada no se conozca ya
create_upload	tools:read	Antes de run_tool, siempre que la herramienta necesite un archivo. Necesita un plan activo, aunque no gaste nada
run_tool	tools:run	Para ejecutar realmente una herramienta. Necesita un plan activo. Esto gasta dinero
get_run	tools:read	Para consultar una llamada a run_tool que devolvió un run_id
wallet_balance	tools:read	Para comprobar los fondos disponibles, o después de un error de insufficient_funds
remember_tool_choice	tools:read	Solo cuando indiques explícitamente que una elección debe mantenerse. No gasta nada
forget_tool_choice	tools:read	Cuando quieras que se te ofrezca la elección de nuevo

Esa es la lista completa. No hay una superficie MCP por herramienta: las 80 herramientas del catálogo se alcanzan a través de run_tool por slug, que es lo que mantiene la lista de herramientas lo suficientemente pequeña para que un agente pueda razonar sobre ella.

Lo que ve el agente

discover_tools toma un query en lenguaje natural y un limit opcional (por defecto 5, máximo 20). Cada resultado incluye un slug, orientación sobre cuándo usarlo, su precio y una entrada de muestra rellenable, por lo que el agente normalmente puede omitir inspect_tool.

Quién elige la herramienta

Tú. Goro nunca elige una: run_tool toma un slug exacto, por lo que cuando varias herramientas pueden hacer un trabajo, la elección ocurre en el agente.

Por defecto no se le permite hacer esa elección en silencio. discover_tools devuelve un campo choose que le indica al agente que te muestre los candidatos con sus precios y pregunte cuál quieres. Eso importa porque los precios no están cerca: cinco herramientas pueden generarte una imagen, desde $0.01 hasta $0.27 por llamada, y que te cobren por una que nunca se te mostró no es una buena sorpresa.

Tres cosas omiten la pregunta:

• Nombraste la herramienta. "Usa nano banana pro para esto" ya es una respuesta.
• Solo una herramienta coincide. No hay nada entre lo que elegir, aunque el agente debería decirte igualmente en qué está a punto de gastar.
• Dijiste que siempre use una. Dile al agente "usa siempre X para imágenes", "recuerda eso" o "deja de preguntarme", y llama a remember_tool_choice. A partir de entonces, discover_tools devuelve your_preference para esa categoría y el agente la usa sin preguntar.

Una preferencia se guarda solo cuando pides una. Elegir una herramienta para un trabajo individual no es una instrucción permanente, y tratarla como tal significaría que nunca se te vuelve a ofrecer la opción más barata. Una elección guardada por categoría (imagen, video, voz, búsqueda, redes sociales, mapas, personas, comercio electrónico). Di que quieres elegir de nuevo y el agente llama a forget_tool_choice.

Nota

Esto es una instrucción para el agente, no un bloqueo. Goro puede decirle a un cliente que te pregunte y puede negarse a adivinar en tu nombre, pero no puede entrar en el cliente y forzar un mensaje. Un agente bien comportado lo sigue; trata remember_tool_choice como el control confiable, ya que ese se aplica del lado del servidor.

La API HTTP y la CLI no se ven afectadas: ambas ya requieren que nombres un slug, por lo que no hay nada que nadie deba elegir.

run_tool bloquea hasta unos 25 segundos. Una herramienta rápida devuelve sus filas en esa misma respuesta. Una más lenta devuelve un run_id y una instrucción explícita de consultar get_run hasta que el estado sea terminal.

wallet_balance devuelve el saldo disponible, el plan del espacio de trabajo, el crédito incluido no vencido, renews_at y un top_up_url. La URL y, en un plan, la fecha de renovación son lo que un agente debería mostrar a un humano cuando los fondos se agotan.

Envío de un archivo

Una regla, y importa más de lo que parece: un agente nunca debe leer un archivo en la conversación para poder enviarlo. Los argumentos de las herramientas pasan por la ventana de contexto exactamente igual que los resultados de las herramientas, por lo que una fotografía de 3 MB enviada como image_base64 son aproximadamente un millón de tokens, se trunca y falla la ejecución con algo que parece corrupción de archivo.

create_upload es la forma de evitarlo. Toma un content_type, devuelve un identificador corto más una URL para hacer PUT del archivo, e incluye el curl exacto para ejecutar. El agente sube el archivo con su propio shell y luego pasa el identificador como image_handle en run_tool. Los bytes nunca entran en la conversación, el límite pasa de 3 MB a 10 MB, y el identificador en sí tiene unos treinta caracteres. No reduzcas la imagen para que quepa: el tamaño nunca fue el problema que resuelve la ruta de subida. Subidas documenta todo el flujo.

4. Errores que encontrará un agente

Los errores de las herramientas llevan el mismo code y message que la API HTTP, por lo que un conjunto de instrucciones cubre ambas superficies.

code	Qué debe hacer el agente
validation_error	Lee el array errors, corrige cada campo, reintenta una vez
subscription_required	Detente. El espacio de trabajo no tiene un plan activo. Dile al humano que elija uno en el billing_url del cuerpo
insufficient_funds	Detente. Dile al humano el monto, el top_up_url y, si renews_at está establecido, cuándo vuelve el crédito incluido
budget_exceeded	Detente. La billetera está bien, un límite de gasto está bloqueando. No pidas una recarga
not_found	El slug no existe. Ejecuta discover_tools de nuevo
forbidden	Al token le falta el ámbito que la herramienta necesita. Reautoriza
provider_error	La herramienta falló y no se cobró nada. Es seguro reintentar

Lo que esto comparte con la API

Todo. Las herramientas MCP son envoltorios delgados sobre las mismas rutas de código que /v1/discover, /v1/inspect, /v1/uploads, /v1/run, /v1/runs/{id} y /v1/wallet/balance. Mismo catálogo, mismas retenciones, mismos cobros, mismo libro mayor.

Las filas llegan en la respuesta de run_tool, o en la consulta de get_run que encuentra la ejecución terminada. Consultar una ejecución terminada es la forma admitida de recoger un resultado lento. Los resultados se eliminan una vez recogidos, y después de 24 horas en cualquier caso, por lo que haz que el agente anote cualquier cosa que necesite más adelante. Cuando el resultado es un enlace de medios, de una herramienta de voz o imagen, haz que descargue el archivo también: esos enlaces expiran con el mismo reloj o con el del proveedor del modelo.

Los endpoints detrás de las ocho herramientas.

Esta documentación está creada y alojada en Mintlify, una plataforma de documentación para desarrolladores.