Tutorial: móntale las herramientas de tu app a un agente de la flota

Tienes una app con su API y quieres que un agente de la flota ejecute acciones de esa app: crear una orden, buscar un cliente, cancelar una cita. Este tutorial cubre el patrón completo: qué expone tu app, cómo lo registras en el agente y cómo compruebas que está vivo.

El modelo mental

La app es dueña de sus tools. El agente no sabe nada de la app. Al inicio de cada turno, la flota le conecta al agente un servidor MCP que expone tus tools. Ese servidor le pega a tu API con una llave; tu app decide qué tool existe, quién puede llamarla y cuáles esperan aprobación humana. El modelo nunca arma llamadas HTTP a mano.

Tres capas:

Paso 1: expón un servidor MCP por HTTP

Un endpoint Streamable-HTTP en tu app, por ejemplo https://miapp.com/api/mcp, que:

• Acepte Authorization: Bearer <llave> y con esa llave resuelva tenant y permisos.
• Responda tools/list y tools/call.
• Arranque aunque la llave falte: que devuelva "sin acceso", no que muera.

Es lo mismo que EasyBits sirve en su propio /api/mcp. Con el SDK oficial de MCP para tu lenguaje sale en una tarde. HTTP es el transporte remoto estándar del protocolo y no requiere publicar nada en npm ni instalar nada en el worker. La alternativa stdio (un paquete npm) existe, pero obliga a descargar el paquete en cada turno dentro de la microVM.

Un esqueleto mínimo en Node:

Paso 2: regístralo en el agente (tres llamadas)

Todo va contra un solo endpoint, autenticado con el token del agente:

Con el SDK:

En el siguiente turno el agente ya trae mcp__miapp__*.

Las dos últimas llamadas son distintas y las dos hacen falta. add-mcp mete tu MCP al menú del agente. set-cap-level lo habilita para un grupo. El worker sólo recibe lo que está habilitado; si tu nombre no está ahí, el turno corre sin tus tools y sin error. Si quieres encenderlo sólo para un canal, usa su groupId en lugar de "*".

Paso 3: verifica

Tu MCP debe salir en capabilities[] con secretsPresent: true y en groups["*"].mcpServers. Si falta el secret, la entrada se omite en silencio.

Después manda un turno con un groupId nuevo y pregunta "¿qué herramientas tienes?":

El groupId nuevo importa: la sesión de una conversación fija sus MCPs al arrancar, y probar sobre una conversación vieja puede mostrar la config anterior.

El contrato de tu MCP, en cuatro reglas

• Lista corta, ejecución completa. Si tienes muchas tools, que tools/list devuelva las de uso diario más un discover_tools({query}) y un run_tool({name, params}); tools/call acepta todas. Con 70 tools planas el modelo niega capacidades que sí tiene.
• Ocultar no es permiso. El scope lo aplica tu servidor por la llave. La lista corta sólo ayuda al modelo a elegir.
• needs_confirmation no es error. Para acciones que esperan aprobación humana devuelve un resultado normal, sin isError. Marcado como error, el modelo reintenta.
• Mismo mensaje para "no existe" y "no es de tu scope". Si no, una llave pública enumera el set admin probando nombres.

Confirmación humana

El enforcement es estructural, no un prompt. "Pide permiso antes de cancelar" se cumple casi siempre, y el "casi" es una cita cancelada de verdad.

• El handler de una acción sensible responde needs_confirmation y archiva el payload en una tabla de pendientes. No existe ninguna tool que acepte un token de confirmación: el modelo no tiene por dónde proceder.
• El resumen que ve la persona lo arma el servidor resolviendo la base de datos, nunca el texto del modelo.
• Al confirmar, ejecuta tu app con el payload archivado.
• El buzón de confirmación se autentica con la sesión de tu dashboard, jamás con la llave de API. Si no, el agente se aprobaría a sí mismo.

Multi-tenant

Un FleetAgent por tenant, cada uno con su vault y su llave. El aislamiento es estructural y funciona sin pedir nada.

Lo que no hay que hacer nunca: resolver el tenant desde el texto del prompt. Un tenantId que el MCP "confía" porque venía en appendSystemPrompt es inyección de prompt desde el navegador del cliente.

Checklist

1. /api/mcp Streamable-HTTP con Bearer en tu app.
2. set-secret → add-mcp { url } → set-cap-level { groupId: "*" }.
3. GET /capabilities: secretsPresent: true y tu nombre en mcpServers.
4. Turno con groupId nuevo: "¿qué herramientas tienes?".

Foto de Magda Ehlers en Pexels.