Logotipo de Bitdoze

Guía de Composio MCP: Conecta Codex, Claude Code y Mastra a Más de 1,500 Apps

Guía práctica de Composio MCP: conecta agentes de Codex, Claude Code y Mastra a más de 1,500 apps, añade servidores MCP personalizados, usa triggers y esquiva las trampas de precios de 2026.

Dragos

37 min de lectura

Guía de Composio MCP: potencia tus agentes de IA con una sola capa de herramientas

Composio MCP le da a cada agente que ejecutas la misma capa de herramientas: más de 1,500 integraciones de apps con OAuth gestionado detrás de una sola conexión. En mi día a día eso significa que Codex CLI, omp (oh-my-pi) y pi llegan todos a GitHub, Gmail y YouTube por MCP, mientras mis agentes de Mastra acceden a las mismas cuentas conectadas a través del SDK @composio/mastra. Vincula una cuenta una vez y úsala desde cualquier parte.

Además de las apps del catálogo por defecto (Gmail, GitHub, YouTube, Reddit, Google Search Console, Plausible Analytics), mi cuenta tiene dos servidores MCP personalizados, Ubersuggest y Fish Audio, añadidos directamente desde la pantalla de Apps. Ese banco convierte a los agentes de codificación en una pequeña canalización de contenido (investigación de palabras clave, analítica, datos de vídeo, voz) sin que cada agente guarde su propia copia de cada clave de API.

Esta guía es la versión práctica de esa configuración. Incluye la instalación del CLI, el cableado de clientes para Codex y Claude Code (y cualquier cliente MCP genérico como omp y pi), el ritual de verificación con successful: true, triggers y Composio Bench para la parte orientada a eventos, las trampas de precios de 2026 que nadie más documenta y la recomendación honesta de «cuándo autoalojar en su lugar». Ya cubrí a fondo la parte autoalojada en mi comparativa de Executor.sh vs Composio, así que este artículo enlaza allí en lugar de repetir la guía de Docker. Si estás empezando con la programación con IA, revisa primero esa guía para principiantes y luego vuelve.

Verificado el 2026-09-25

Los precios, los flags del CLI y los endpoints de esta guía se verificaron el 2026-09-25. Composio cambia rápido: vuelve a revisar composio.dev/pricing y el changelog del SDK el día de publicación.

¿Qué Es Composio MCP? Auth Gestionada, Más de 1,500 Apps, Una Conexión

Composio se sitúa entre tus agentes y tus apps. Almacena y refresca tokens OAuth, guarda claves de API y expone cada integración como herramientas que un agente puede llamar. La página principal cuenta más de 1,500 toolkits (GitHub, Gmail, Google Cloud, YouTube, Slack, Notion y siguen). Si el protocolo en sí te es nuevo, lee primero qué es realmente MCP (Model Context Protocol). Composio no es MCP. Es una capa de herramientas a la que llegas por MCP (agentes de CLI) o por un SDK (agentes de framework), y ambas vías comparten las mismas cuentas conectadas. Ese modelo de cuenta compartida es la clave: una conexión de GitHub, reutilizada por Codex en la terminal y por un worker de Mastra en producción.

Dos productos conviven bajo una misma API. Composio For You es la parte de agente personal: tus propias cuentas, cero código, pensado para automatizar tu vida. Composio Platform es para bases de código de aplicaciones donde tus usuarios conectan sus cuentas, con sesiones y auth por usuario. La documentación es directa sobre la división: «Default to Composio Platform for application codebases… Use Composio For You for a personal agent.» En esta guía me quedo en la parte de agente personal, que es lo que la mayoría de operadores en solitario necesita. Si solo quieres un endpoint MCP de consumo para Cursor o Claude Desktop, Composio también ofrece Rube (rube.app/mcp), que conecta herramientas de IA con más de 500 apps con menos ceremonia.

Panel de Auth Configs de Composio Platform: apps OAuth2 gestionadas (Gmail, GitHub, YouTube, Reddit, Google Search Console) más una config personalizada con clave de API para Plausible Analytics

Esa captura es mi página real de Auth Configs. Fíjate en la división de la columna Management: las apps de Google funcionan con OAuth2 gestionado por Composio (rápido de conectar, pero mira la trampa de las apps gestionadas en la sección de precios), mientras Plausible Analytics está en una config Custom que guarda mi propia clave de API. Desde aquí puedes cambiar cualquier toolkit a tu propia app OAuth, que es exactamente lo que la sección de precios te empuja a hacer en volumen.

Señales de madurez que conviene conocer antes de conectarle agentes de producción: el repositorio ComposioHQ/composio tiene 28.7k estrellas y 4.6k forks, con licencia MIT, pero solo contiene los SDK y el CLI. El runtime de la plataforma es de código cerrado. Composio declara SOC 2 Type II e ISO 27001 (verifícalo en su Trust Center antes de escribirlo en un cuestionario de seguridad) y «más de 100M de ejecuciones de herramientas a la semana» en la parte alojada. Es un producto real y financiado, no un envoltorio de fin de semana.

  • OAuth gestionado y auth con clave de API, con refresco de tokens incluido
  • Más de 1,500 toolkits detrás de un único modelo de conexión
  • Tool Router: búsqueda de herramientas por intención, para que 1,500 herramientas no caigan en tu ventana de contexto
  • Triggers y webhooks para trabajo orientado a eventos
  • Servidores MCP personalizados que puedes registrar gratis (así encajan Ubersuggest y Fish Audio)
  • Una cuenta conectada reutilizada entre agentes de terminal, agentes de framework y clientes MCP

Arquitectura de Composio: una capa de herramientas que conecta Codex CLI, omp, pi y agentes de Mastra con apps conectadas y servidores MCP personalizados

Sé consciente de en qué confías

El runtime es de código cerrado y el alojamiento es en EE. UU. por defecto. Hoy no hay región UE; la retención cero de datos (ZDR), el BAA y la lista de IPs permitidas son complementos de pago en el plan Scale, y solo se incluyen en Enterprise. Si el GDPR o la residencia de datos es un requisito innegociable, lee la sección de autoalojamiento antes de comprometerte. Asume también que cada llamada a herramienta pasa por su nube, así que el radio de impacto y la latencia pasan por un tercero.

Cómo Configurar Composio MCP con Tus Agentes de Codificación

Este es el camino feliz de cero a un login de agente funcional, en unos 10 minutos. Una cuenta gratuita es suficiente (sin tarjeta, y el plan gratis tiene tope duro, así que no hay factura sorpresa). Hay dos modos de login y elegir el equivocado es el fallo de configuración más común: un login humano para uso interactivo y un login de agente desatendido para máquinas de CI y agentes sin interfaz que no pueden abrir un navegador. Ambos están abajo.

Qué Necesitas Antes de Empezar

  • Una cuenta de Composio (plan gratis, sin tarjeta). Para uso SaaS en producción, planea registrar tus propias apps OAuth para los toolkits que te importen (la sección de precios explica por qué).
  • Node.js 22.22.3 o superior (el SDK de TS es solo ESM) o Python 3.10+ si usas el SDK de Python.
  • Un agente de codificación: Codex CLI o Claude Code oficialmente; omp y pi funcionan como clientes MCP genéricos.
  • Un plan para manejar COMPOSIO_API_KEY: variable de entorno o almacén de secretos, nunca en el repositorio. Lo mismo para agent.json y .env.
  • Opcional: cuentas de Fish Audio y Ubersuggest si quieres seguir las demos de MCP personalizados.
  • Para el apéndice autoalojado: cualquier host Docker o VPS pequeño (1 GB de RAM sobra), puerto 4788.

Comprobación rápida antes de tocar Composio:

bash
node --version    # want v22.22.3+ for the TS SDK path
python3 --version # want 3.10+ for the Python SDK path

Instala el CLI de Composio y Conecta Tu Primera App

Instala el CLI. El instalador coloca el binario en ~/.local/bin/composio:

bash
curl -fsSL https://composio.dev/install | sh
export PATH="$HOME/.local/bin:$PATH"

El instalador modifica el perfil de tu shell

Las versiones recientes del CLI editan por defecto los archivos de arranque de zsh/bash/fish para ajustar el PATH. Eso interfiere con los gestores de dotfiles y ensucia las imágenes de CI. Desactívalo y configura el PATH tú mismo:

bash
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none sh

Ahora inicia sesión y conecta tu primera app:

bash
composio login                 # browser flow, org/project picker
composio login -y              # scripts/CI: accept session defaults
composio link github           # connect GitHub (opens consent screen)
composio link github --no-wait # non-blocking variant, JSON to stdout
composio whoami                # confirm who you are (no longer prints API keys)
composio upgrade               # self-update when you come back later

Login humano

Para uso interactivo en un portátil:

bash
composio login
composio link github
composio whoami

El flujo del navegador te permite elegir organización y proyecto. -y acepta los valores por defecto de la sesión para scripts. Una URL de login pendiente caduca a los 10 minutos, así que no dejes una en un log de CI. Las conexiones OAuth incompletas también caducan automáticamente a los 10 minutos.

Login de agente desatendido (CI/agentes)

Para agentes sin interfaz que no pueden abrir un navegador, crea una cuenta de agente dedicada:

bash
composio login --agent
composio agent whoami
COMPOSIO_API_KEY="$(jq -er '.composio.api_key' ~/.composio/agent.json)"

composio agent whoami debe mostrar account_type: "agent", status: "READY" y logged_in: true. La identidad queda en ~/.composio/agent.json con permisos 0600. El campo composio.api_key es la clave de tu proyecto.

Dos trampas: --agent no se puede combinar con los flags --no-browser o --key, y la cuenta de agente no hereda las apps conectadas de tu cuenta humana. Es una cuenta separada por diseño, así que ejecuta composio link <app> para cada app que el agente necesite. Nunca subas agent.json al repositorio.

Fallos típicos en este paso: una URL de login caducada (10 minutos) significa volver a ejecutar composio login. composio: command not found tras instalar significa que el PATH no está exportado en este shell. Apps que faltan en la cuenta de agente significa que las vinculaste a la cuenta humana.

Añade Composio MCP a Codex, Claude Code, omp y pi

Los agentes de codificación se integran mediante un Agent Skill más MCP. La instalación es una línea:

bash
npx skills add ComposioHQ/composio --skill composio

Eso crea un SKILL.md que el agente lee para saber cómo manejar Composio. Si el formato de skills te es nuevo, consulta Agent Skills (archivos SKILL.md). Clientes oficiales: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, OpenClaw, OpenCode, Cline y Grok Build (existen plugins nativos para Claude Code y Codex). omp y pi no están en esa lista. Yo los uso igualmente como clientes MCP genéricos y funciona, pero tómalo como «cualquier cliente MCP puede conectarse» y no como «soportado oficialmente».

Codex CLI

bash
npx skills add ComposioHQ/composio --skill composio
# MCP endpoint comes from the Composio dashboard (session-based MCP)
codex mcp add composio "$COMPOSIO_MCP_URL"
codex mcp list   # verify it is registered

Codex también tiene soporte nativo del plugin de Composio. En cualquier caso, la URL de MCP debe llevar tu identidad (ver el aviso de error más abajo).

Claude Code

bash
npx skills add ComposioHQ/composio --skill composio
claude mcp add --transport http composio "$COMPOSIO_MCP_URL"
# then inside Claude Code: /mcp to sign in and confirm tools load

Claude Code también tiene un plugin nativo; la vía de skill más MCP es la que lo mantiene coherente con tus otros agentes.

omp y pi (cliente MCP genérico)

omp (oh-my-pi) y pi no están en la lista oficial de clientes de Composio, pero ambos hablan MCP. Apúntalos a la misma URL de MCP basada en sesión, con la clave de API como cabecera:

bash
# same URL and x-api-key requirements as any other client
export COMPOSIO_API_KEY="ck_..."
# register https://mcp.composio.dev/... ?user_id=... in your client's MCP config

Yo lo combino con dar memoria compartida a los agentes con Hindsight para que omp y pi mantengan el contexto entre sesiones mientras Composio gestiona las herramientas. Considera también reducir el radio de impacto antes de dar a los agentes acceso real a herramientas: ejecuta herramientas CLI de IA en Docker o Podman para que un agente confundido no pueda tocar tu host.

La trampa del 401 (dos causas)

Las URL de MCP deben incluir ?user_id= o ?connected_account_id= (obligatorio desde el 15 de enero de 2026), y las organizaciones creadas después del 5 de marzo de 2026 requieren una cabecera x-api-key en cada petición MCP o recibirás un 401. Ambas se arreglan en la configuración; no depures el prompt de tu agente cuando es el transporte el que te rechaza. Puedes desactivar el requisito de clave de API con PATCH /api/v3/org/project/config, pero yo no lo haría.

Regenera las URL de MCP filtradas

Las versiones antiguas de @composio/openai imprimían por stdout las URL de servidores MCP con credenciales incrustadas. Según el changelog de Composio, trata cualquier URL así como expuesta y regenera el endpoint. Ten en cuenta también que el antiguo endpoint mcp.composio.dev de un solo toolkit está retirado: los tutoriales anteriores a finales de 2025 fallarán. La documentación ahora te dirige a MCP basado en sesión en lugar de servidores MCP por toolkit.

Una nota operativa más antes de continuar. Cuando un agente puede llamar herramientas, puede borrar correo, subir código y rotar infraestructura. Ese es el objetivo, y también el radio de impacto. Aísla el CLI en un sandbox (enlace arriba), usa una cuenta de agente dedicada en lugar de tu cuenta humana y aprende cómo deshacer conexiones: eliminar una cuenta conectada no revoca los tokens en origen. Llama primero a POST /api/v3.1/connected_accounts/{id}/revoke, comprueba revoked_tokens en la respuesta (best-effort) y después elimina.

Verifica Que Funciona: Login del Agente y la Prueba de «successful: true»

No te fíes de una lista de herramientas. Una consulta de esquema demuestra que la herramienta existe, no que la ejecución funciona. La prueba de humo oficial llama a una herramienta sin auth y debe devolver "successful": true:

bash
curl --fail-with-body --silent https://backend.composio.dev/api/v3.1/tools/execute/HACKERNEWS_GET_USER \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"arguments":{"username":"pg"}}'

successful: true, o no ocurrió

Exige "successful": true en la respuesta. Un 401, un payload de esquema o un 200 con successful: false no valen. Este único curl separa «la auth está conectada» de «el prompt de mi agente está mal».

Después haz la comprobación real de extremo a extremo: pide al agente una pequeña acción en GitHub o Gmail («marca este repo con estrella» o «crea un borrador de etiqueta de prueba») y confirma la llamada en el registro de llamadas de herramientas del panel de Composio. El log es la fuente de verdad sobre lo que el agente hizo realmente.

  • composio agent whoami muestra status: "READY"
  • Servidor MCP listado en tu cliente (codex mcp list, /mcp en Claude Code)
  • El curl de prueba devuelve "successful": true
  • El registro de llamadas del panel muestra la acción real de extremo a extremo

Mapa compacto de fallos: un 401 al conectar por MCP significa que falta x-api-key (o la clave es incorrecta) junto con la config de MCP de tu organización. URL rechazada significa que falta ?user_id=. Una respuesta con solo esquema significa que consultaste herramientas, no que ejecutaste una. Y si necesitas desactivar require_mcp_api_key, es PATCH /api/v3/org/project/config; de nuevo: no recomendado.

Integración de Composio con Mastra: el SDK @composio/mastra

Los agentes de terminal obtienen herramientas por MCP. Los agentes de framework las obtienen del SDK, contra las mismas cuentas conectadas. El provider @composio/mastra es solo TypeScript y la línea 0.10.x apunta a Mastra v1 (con breaking changes frente al antiguo provider v0.x), así que fija tus versiones. Esta es la vía que uso para todo lo que corre desatendido: sesiones, herramientas tipadas y un registro en el panel que puedo auditar.

Sesiones, Tool Router y Modo Strict Explicados

La forma recomendada es sesiones primero. Una sesión lleva toolkits, configuración de auth, estado del sandbox y archivos para un usuario, y session.tools() devuelve el conjunto de herramientas con esquemas de entrada y salida para que Mastra también valide los resultados:

ts
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const composio = new Composio({ provider: new MastraProvider({ strict: true }) });
const session = await composio.create("user_123");
const tools = await session.tools();

const agent = new Agent({
  id: "seo-agent",
  name: "SEO Agent",
  instructions: "Research keywords and summarize trends.",
  model: openai("gpt-5.2"),
  tools,
});

Define COMPOSIO_API_KEY en el entorno. Las sesiones son reutilizables vía session_id y ajustables con session.update(), que es como cambias de toolkits por tarea sin volver a aprovisionar la auth.

Sesión mínima

ts
const composio = new Composio({ provider: new MastraProvider() });
const session = await composio.create("user_123");
const tools = await session.tools();

Suficiente para un agente personal. Los esquemas pasan tal cual.

Modo strict + herramientas precargadas

ts
const composio = new Composio({ provider: new MastraProvider({ strict: true }) });
const session = await composio.create("user_123", {
  toolkits: ["GMAIL", "GITHUB"],
});
const tools = await session.tools();

El modo strict normaliza los esquemas para las salidas estructuradas de OpenAI: todas las propiedades requeridas, objetos cerrados, los opcionales aceptan null y los nulos se eliminan antes de ejecutar. Precarga solo los toolkits que más usas (unas 20 herramientas o menos) en lugar de todo el catálogo.

Fijar versiones de toolkits (producción)

ts
const session = await composio.create("user_123", {
  toolkitVersions: { GMAIL: "2026-08-01", GITHUB: "2026-07-15" },
});

Fija todo aquello cuyos slugs de herramientas referencien tus prompts o evals por nombre. El cambio de esquemas es real (detalles en modos de fallo). La sintaxis exacta de versiones cambia entre releases del SDK; fija primero @composio/core y @composio/mastra, y luego los toolkits.

Tool Router es la solución para la ventana de contexto. En lugar de cargar 1,500 definiciones de herramientas, los agentes descubren herramientas en tiempo de ejecución mediante la metaherramienta COMPOSIO_SEARCH_TOOLS. Usa SESSION_PRESET_DIRECT_TOOLS para agentes acotados que nunca deberían buscar, y mantén las herramientas precargadas al puñado que el agente necesita en cada ejecución. Las herramientas personalizadas solo existen en sesiones de Tool Router.

Aristas del SDK de TS

El SDK de TS es solo ESM y pide Node 22.22.3+. Pasar apiKey: null desactiva el fallback de entorno (pasa undefined para mantenerlo). verifyWebhook es async y requiere los parámetros id y timestamp. Algunas herramientas de Composio referencian entradas $defs que el backend no emite; el provider cae a un esquema laxo con un aviso por herramienta en lugar de fallar tools.get(). Los esquemas que no se pueden hacer estrictos (objetos de claves arbitrarias, allOf, prefixItems, $ref sin resolver) caen silenciosamente a permisivo con un aviso.

Verifica esta capa igual que la del CLI: session.tools() devuelve una lista no vacía, luego ejecuta una acción de Gmail o GitHub y confírmala en el registro del panel. Modos de fallo esperables: avisos de $ref sin resolver (fallback, no fatal), deriva de esquemas (1,445 slugs de enums renombrados en 37 toolkits y unas 230 herramientas marcadas como deprecated; fija toolkitVersions como tu deshacer) y sorpresas con archivos (URL prefirmadas con TTL de 1 hora, subida/descarga automática desactivada por defecto tras dangerouslyAllowAutoUploadDownloadFiles, más una lista de denegación de rutas sensibles para .ssh, .env, .aws y compañía). Existe proxy execute para endpoints que no están envueltos como herramientas, pero solo para el mismo dominio registrable (400 OriginMismatch) y con un tope de payload de 250 MB.

Mi Banco de Apps: Toolkits por Defecto más Servidores MCP Personalizados

Esta es la parte que no he visto documentada en ningún otro sitio, así que aquí va mi banco real. La vista de Apps muestra seis apps conectadas: cuatro del catálogo por defecto (YouTube, Reddit, Google Search Console y Plausible Analytics) más dos servidores MCP personalizados que registré yo: Ubersuggest y Fish Audio. (Las conexiones de Gmail y GitHub también viven a nivel de plataforma, como muestra la captura de Auth Configs anterior). Composio permite añadir servidores MCP personalizados gratis (su FAQ: «Yes, if the app has an MCP server. You can easily add custom MCP servers to Composio for free.»), y Tool Router evita que los servidores extra inflen el contexto.

Pantalla de Apps de Composio con seis apps conectadas: YouTube, Reddit, Google Search Console y Plausible del catálogo, más fish.audio y ubersuggest añadidos vía Add Custom MCP

El botón «+ Add Custom MCP» de arriba a la derecha es todo el truco: pega una URL de MCP remota, completa el flujo de auth que use y el servidor se une a la misma lista de Apps como ciudadano de primera clase, accesible por Codex en la terminal y por Mastra a través de session.tools(), igual que un toolkit nativo. La forma de la canalización en mi caso:

  • Ubersuggest (MCP personalizado, investigación de palabras clave), Google Search Console (datos de consultas y rankings) y Plausible (analítica del sitio en una config de auth con clave de API) alimentan al agente de keywords: qué busca la gente, qué ya posiciona, qué ya recibe tráfico en mis sitios.
  • YouTube alimenta al agente de contenido: datos de vídeos y temas. Gmail, GitHub y Reddit cubren las cuentas del día a día con OAuth gestionado.
  • Fish Audio (MCP personalizado) alimenta al agente de narración: texto a voz y clonación de voz para la salida.

Los agentes acaban con información detallada y actual en lugar de volúmenes de keywords alucinados. La misma idea se generaliza: ya cubrí BrightData MCP para web scraping (tira de la plataforma de datos web Bright Data) como fuente de datos web, y memoria de IA autoalojada vía un servidor MCP (Cognee) como fuente de memoria. Ambas encajan en el mismo registro de MCP personalizados.

Un servidor tiene documentación pública que vale la pena repasar: Fish Audio expone un MCP por HTTP streamable en https://api.fish.audio/mcp. La auth es OAuth mediante un popup del navegador, la facturación descuenta de los créditos del paquete del plan (no de los créditos de API de desarrollador), la generación de imagen/vídeo se cotiza y requiere confirmación, el vídeo necesita el plan Plus o superior, las generaciones fallidas se reembolsan y las subidas se eliminan automáticamente a los 7 días. Comandos de conexión directamente de su documentación:

Fish Audio: Codex CLI

bash
codex mcp add fish-audio https://api.fish.audio/mcp
codex mcp login fish-audio
codex mcp list   # verify

Fish Audio: Claude Code

bash
claude mcp add --transport http fish-audio https://api.fish.audio/mcp
# then inside Claude Code: /mcp to sign in

Cómo funcionan los créditos de Fish Audio

Las generaciones por MCP descuentan de los créditos del paquete del plan, no del saldo separado de la API de desarrollador. La generación de vídeo requiere el plan Plus o superior. Una llamada TTS basta para verificar: observa cómo se mueve el uso de créditos en el panel de Fish Audio después de que el agente corra.

Fish Audio funciona por separado (como arriba) o registrado dentro de Composio como MCP personalizado para que las mismas voces estén disponibles para los agentes de Mastra a través de session.tools(). Yo lo uso de la segunda forma: ponerlo detrás de Composio significa una sola historia de auth y un registro de herramientas compartido con el resto del banco.

  • YouTube, Reddit, Google Search Console: apps conectadas del catálogo por defecto con OAuth2 gestionado
  • Plausible: app del catálogo en una config de auth personalizada con clave de API (analítica autoalojada en la que confío)
  • Ubersuggest: investigación de palabras clave y volúmenes, añadido vía «+ Add Custom MCP»
  • Fish Audio: TTS y clonación de voz, añadido vía «+ Add Custom MCP»
  • Gmail y GitHub: conectados a nivel de plataforma para los agentes que los necesitan

Verifica con una ejecución real: pide al agente ideas de palabras clave sobre un tema, observa cómo llama a Ubersuggest, Search Console y Plausible, luego pide una línea de voz y genera un TTS con Fish Audio. Revisa después el registro de llamadas de herramientas de Composio y el panel de Fish Audio.

Triggers y Bench de Composio: Eventos que Entran, Benchmarks que Salen

Las llamadas a herramientas son el modelo pull: el agente pide, Composio ejecuta. Dos piezas más cubren la dirección contraria y la pregunta de «si esto siquiera funciona bien»: los triggers empujan eventos de apps hacia ti, y Bench mide si tu agente es siquiera bueno usando herramientas.

Triggers: eventos de apps entregados a tu webhook

Un tipo de trigger es una plantilla que una app expone, como GITHUB_COMMIT_EVENT, un nuevo mensaje de Gmail o un nuevo DM de Slack. Una instancia de trigger es ese tipo activado para una cuenta conectada, con su propio ID ti_* que puedes habilitar, deshabilitar o borrar de forma independiente. Creas instancias con POST /api/v3.1/trigger_instances/{slug}/upsert (o el SDK), luego registras una URL de webhook por proyecto y Composio envía por POST cada evento ahí, firmado con las cabeceras webhook-id, webhook-timestamp y webhook-signature. Guarda el secreto como COMPOSIO_WEBHOOK_SECRET y verifica antes de confiar en cualquier payload.

La latencia depende del proveedor, no de ti: Slack, Asana, Notion y Outlook empujan en casi tiempo real, mientras que Gmail y Google Calendar se sondean, con un mínimo forzado de 15 minutos en el OAuth gestionado por Composio (la sección de precios explica por qué tu propia app OAuth lo baja a sondeo de 1 minuto). Para desarrollo local, el streaming de composio triggers del CLI o subscribe() en el SDK reenvía eventos a tu máquina por un WebSocket firmado exactamente como en producción, así que puedes probar el handler real antes de tener una URL pública.

  • Una URL de webhook por proyecto recibe cada evento de trigger, firmado
  • Tiempo real para proveedores push, sondeo de ~15 min para Gmail/Calendar con auth gestionada
  • Suscríbete a eventos de ciclo de vida: composio.connected_account.expired y composio.trigger.disabled te avisan cuando la auth o un trigger mueren en silencio
  • Facturación: 50K eventos de trigger/mes gratis; los eventos con auth gestionada topan en 10K y luego $0.005 cada uno

En mi stack esto es lo que convierte el banco en una canalización: un cambio en Search Console o Plausible, una nueva mención en Reddit, un comentario de YouTube: cualquiera puede disparar un evento que despierte a un agente de Mastra en lugar de que el agente sondee con un cron.

Composio Bench: comprueba si tu agente sabe usar herramientas de verdad

Composio también mantiene Bench, un benchmark público que ejecuta harnesses de agentes reales contra tareas de uso de herramientas con estado, no el típico quiz sintético de function-calling. El dataset estrella, composio-hard-30, son 30 tareas que abarcan flujos multi-app, reconciliación exacta de estado, escrituras con guardas, batching y paginación. Un evaluador fijo comprueba el estado final de cada app que la tarea tocó; cada comprobación debe pasar, sin crédito parcial. Es un listón mucho más duro que «si el modelo eligió la función correcta».

Cada página de harness (hay una para Pi Agent, entre otros) reporta tasa de éxito y tiempo por tarea por modelo. Uso práctico: antes de conectar un modelo o agente nuevo a tus cuentas conectadas, mira sus números en Bench: una combinación que no supera los flujos multi-app ahí tampoco ejecutará con fiabilidad una canalización de investigación de keywords. También sirve como anticipo de cómo los modelos subyacentes manejan estructuras de API reales, que es lo mismo que me importa al elegir entre los LLMs open source para agentes de codificación.

Precios de Composio en 2026: las Cuentas del Plan Gratis y la Trampa de las Apps Gestionadas

Casi todas las páginas de terceros tienen precios desactualizados («1,000 acciones gratis», «Pro a $49/mes»). Esos números están mal. Confía solo en composio.dev/pricing, y revísalo el día de publicación.

Fechas del cambio de precios

Los precios nuevos aplican a registros a partir del 15 de agosto de 2026. Los clientes existentes mantienen las condiciones anteriores hasta el 31 de diciembre de 2026. Las llamadas a herramientas premium se facturan a todos los clientes desde el 10 de septiembre de 2026. Si lees una comparativa escrita antes de eso, ignora sus números.

Lo que los planes actuales dicen realmente:

Concepto Gratis Scale ($29/mes)
Llamadas a herramientas 100,000/mes, tope duro (el uso se pausa, sin factura sorpresa) crédito de uso de $29 mensuales (sin arrastre), luego $0.0003/llamada
Eventos de trigger 50,000/mes crédito, luego $0.003/evento
Miembros del equipo 3 más (consulta la página)
Límite de la API 2,000 req/min 10,000 req/min
Cuentas conectadas ilimitadas ilimitadas
Herramientas personalizadas y MCP incluido incluido
Retención de logs 7 días 30 días

La trampa de las apps gestionadas es el mayor riesgo de coste

Las apps OAuth gestionadas por Composio (sus apps cliente compartidas) solo consumen 20K de tus 100K llamadas gratis; pasado eso son $0.0005/llamada. Los eventos de trigger gestionados topan en 10K gratis y luego $0.005, y las conexiones gestionadas en 1K gratis y luego $0.10/conexión. Trae tu propia app OAuth y se aplica la cuota completa. Consecuencia práctica: registra pronto tus propias apps OAuth de Google/Microsoft (la revisión tarda de días a semanas) o pagarás exceso mientras un plan «gratis» queda sin usar.

Las herramientas premium se facturan aparte al coste del proveedor más un 5%: búsqueda web vía Exa o Tavily unos $0.008/búsqueda, SerpAPI unos $0.011, Browser Use unos $0.70/tarea, Google Veo unos $1.20/vídeo, imagen de Gemini unos $0.14/imagen. Tómalos como aproximados y revísalos. Complementos en Scale: ejecución en sandbox +$0.0001/llamada (10K gratis), ejecución directa fuera de una Session +$0.0001/llamada (10K gratis; la ejecución dentro de una Session es la vía incluida), proxy execute +$0.0002/llamada (1K gratis), más BAA, lista de IPs permitidas y ZDR a tarifas pequeñas por llamada. Una nota obsoleta que ignorar: una entrada antigua del changelog aún dice que los sandboxes «no se facturan hoy». La página de precios ya mide las llamadas a sandbox, así que presupuéstalas. Enterprise añade SSO/SCIM, claves KMS gestionadas por el cliente y volumen personalizado.

Dos realidades de coste más. El sondeo de triggers está limitado a un mínimo de 15 minutos con OAuth gestionado (forzado por la API desde el 15 de abril de 2026); el sondeo de 1 minuto necesita tu propia app OAuth, si no, usa triggers por webhook. Y cada reconsulta cuesta dinero: una comparativa de terceros de kanopylabs.com describe una factura que saltó de $200 a $1,400/mes por agentes que reconsultaban datos de Salesforce para «verificar», arreglado con reglas en el prompt y caché corta de resultados. No son mis números, pero el mecanismo es evidente en cuanto ves un bucle de agente.

  • Quédate en Gratis hasta que el tope duro te pause de verdad; en la práctica son meses de uso en solitario
  • Si subes a Scale, pon límites de gasto y trata el crédito de $29 como tu presupuesto
  • Trae tus propias apps OAuth para todo lo que llames en volumen (cuota gratis completa)
  • Prefiere la ejecución en sesión sobre la directa, y evita las herramientas premium o ponles tope
  • Indica en los prompts que los agentes no reconsulten «para verificar», y cachea resultados de 30 a 60 segundos
  • Exporta los logs si depuras desde ellos: retención de 7 días en Gratis, 30 en Scale

Orden de magnitud para un operador en solitario con varios agentes: de $0 a $29/mes en Composio más tu factura de tokens del LLM. La suscripción en sí es pequeña. Los excesos de apps gestionadas y las herramientas premium son lo que infla la factura.

Cuándo No Usar Composio: Autoalojamiento y Alternativas

El autoalojamiento de Composio es solo Enterprise y requiere pasar por ventas (el issue #291 de GitHub pidiendo autoalojamiento self-serve lleva abierto desde 2024). Así que la pregunta de «cuándo no» es en realidad «cuándo gana otro». Composio pierde cuando llamas a tus propias APIs a gran volumen, cuando la residencia en la UE es obligatoria, cuando un runtime cerrado te incomoda o cuando necesitas un coste de infra predecible en lugar de precio por llamada. La forma útil de comparar el campo es por hueco de arquitectura, no por checklist de funciones: MCP proxy vs MCP de flujos de trabajo vs API unificada vs warehouse-first vs gateway autoalojado vs plataforma open source.

Executor.sh: la Alternativa Autoalojada a Composio

Executor.sh es la opción autoalojada que destaco, y no repetiré aquí la instalación: el recorrido completo de Docker y Dokploy está en mi comparativa de Executor.sh vs Composio. Datos que importan para la decisión: licencia MIT, unas 3,982 estrellas de GitHub a 25 de septiembre de 2026 (creció desde unas 2,600 en julio; revísalo el día de publicación), desarrollo activo en TypeScript, MCP más OpenAPI más GraphQL más herramientas JS personalizadas, un entorno de ejecución en sandbox con inyección de credenciales desde el host y un motor de políticas. Es YC S26.

La pista de ejecución en una línea es ghcr.io/rhyssullivan/executor-selfhost:latest en el puerto 4788, y un VPS de 1 GB de RAM es suficiente. Cuentas de coste: $0 de software en un VPS de clase Hetzner a unos 4.5–6 euros al mes que ya mantienes para otras cosas (o Cloudflare Workers en el plan gratis). La contrapartida es honesta: aportas tus propias especificaciones OpenAPI/GraphQL/MCP, no hay catálogo OAuth gestionado. Lo que recuperas es control sobre las credenciales (nunca salen de tu host) y un truco de contexto: miles de definiciones de herramientas colapsan a aproximadamente una herramienta en contexto (Executor afirma pasar de unos 278,800 tokens a unos 1,044; afirmación del proveedor, mídelo tú).

La guía completa está en el artículo comparativo

Los pasos de Docker, Compose y Dokploy ya están publicados. Esta guía se ciñe a los criterios de decisión.

Lee la comparativa de Executor.sh vs Composio

ACI.dev, Pipedream, Zapier MCP y el Resto del Campo

Abajo está el mapa por hueco de arquitectura. Cada fila tiene una forma que encaja en un problema distinto; elegir por hueco gana a elegir por logo.

Alternativas a Composio por hueco de arquitectura: MCP proxy, gateway autoalojado, MCP de flujos de trabajo, API unificada, warehouse-first, tienda curada de herramientas

Hueco Producto Datos clave Elige esto cuando
MCP proxy (gestionado) Composio más de 1,500 toolkits, OAuth gestionado, sesiones, triggers la auth de SaaS es lo difícil y quieres una conexión para todo
Gateway autoalojado Executor.sh MIT, Docker/Workers, MCP+OpenAPI+GraphQL, credenciales en el host APIs propias, residencia en la UE o control de credenciales
Plataforma open source ACI.dev Apache-2.0, ~4,899 estrellas, Docker+Postgres+Redis, más de 600 herramientas declaradas quieres una plataforma abierta que puedas forkear; revisa el mantenimiento (último push en mayo de 2026 en el momento de la investigación)
MCP de flujos Pipedream MCP, Zapier MCP Pipedream: más de 10K herramientas en 2,700+ apps (adquirida por Workday, nov. 2025). Zapier: gran catálogo con aprobaciones human-in-the-loop las automatizaciones por eventos ganan a las herramientas por llamada
MCP de flujos (autoalojado) n8n motor de flujos autoalojado con soporte MCP quieres triggers y flujos en tu propia máquina: autoaloja n8n para automatización de flujos
API unificada Apideck MCP 229 herramientas autogeneradas en 9 categorías (lanzado en mayo de 2026) la portabilidad entre proveedores importa más que la profundidad por proveedor
Warehouse-first Peliqan alojado en la UE, 250+ conectores, SQL entre fuentes, writeback con auditoría residencia de datos y acceso orientado a analítica
Tienda curada de herramientas Toolhouse, MintMCP, Smithery Toolhouse: unas 150 integraciones, ejecución en edge (precios de fuentes externas); MintMCP: gateway empresarial; Smithery: registro MCP quieres menos herramientas pero más afiladas, o una puerta de entrada empresarial

Aviso de cifras sin verificar

Los límites actuales del plan gratis de Zapier MCP y los precios de Toolhouse no estaban verificados en el momento de la investigación (2026-09-25). Los datos de Pipedream/Workday y Apideck vienen de fuentes secundarias. Consulta las páginas oficiales de los proveedores antes de citar esto en serio. Eliminé las filas que no pude verificar.

¿Por qué no existe un Composio autoalojado?

El runtime de Composio es cerrado y el autoalojamiento es una oferta Enterprise que requiere pasar por ventas. El issue #291 de la comunidad lleva abierto desde 2024. La energía open source de este espacio se fue a Executor.sh y ACI.dev. Si el autoalojamiento es un requisito hoy, esas son tus opciones realistas.

El Veredicto: Una Capa de Herramientas, Tres Formas de Ejecutarla

Aquí va la versión corta de lo que realmente recomiendo. Usa Composio alojado para SaaS con mucho OAuth (Gmail, YouTube, Google Search Console, GitHub): el plan gratis da en la práctica para meses de uso en solitario, y el refresco de tokens gestionado es genuinamente pesado de construir. Usa un gateway autoalojado (Executor.sh o ACI.dev) para tus propias APIs, alto volumen o residencia en la UE. Ejecuta el híbrido cuando se den ambas: gestionado donde la auth es difícil, autoalojado donde el volumen es alto. Ese híbrido es lo que tiene mi stack.

Flujo de decisión: Composio para SaaS con mucho OAuth, gateway autoalojado para APIs propias, híbrido cuando aplican ambos

Reglas de decisión, no corazonadas:

  • Elige Composio cuando los agentes necesiten Gmail/Google/YouTube/GitHub, quieras una conexión entre Codex, omp, pi y Mastra, y los precios Gratis/Scale encajen (vigila el tope de apps gestionadas).
  • Elige autoalojado (Executor.sh/ACI) cuando las APIs sean tuyas, el volumen sea alto, las credenciales no deban salir de tu red o la residencia en la UE sea innegociable.
  • Elige MCP de flujos (n8n, Pipedream, Zapier) cuando el trabajo sean canalizaciones por eventos y no herramientas por llamada.
  • Elijas la capa que elijas, decide aparte qué modelo va detrás de las herramientas; los LLMs open source para agentes de codificación ya son suficientemente buenos para la mayoría de bucles de llamadas a herramientas.

Luego haz las cosas aburridas que hacen que sobreviva al contacto con producción: fija versiones de toolkits, aísla el CLI en un sandbox, pon topes de gasto, revoca tokens en origen al desmontar y verifica con successful: true cada vez. Si no has leído el análisis a fondo de la parte autoalojada, está en mi comparativa de Executor.sh vs Composio.

Empieza con Composio Guía de autoalojamiento de Executor.sh

FAQ

¿De verdad necesito otra suscripción SaaS para herramientas de agente?

Probablemente no el primer día. El plan Gratis son 100K llamadas a herramientas y 50K eventos de trigger al mes, con tope duro, así que el uso se pausa en lugar de facturarte. Eso cubre meses de uso multiagente en solitario. Paga $29/mes por Scale solo cuando el tope pause trabajo real, y trata el crédito incluido de $29 más los topes de gasto como tu presupuesto. Las partidas que de verdad duelen son los excesos de apps gestionadas y las herramientas premium, no la suscripción.

¿Se pueden filtrar mis credenciales a través de su nube?

Los tokens los guarda Composio y se redactan en las respuestas de la API, pero el runtime es cerrado y el alojamiento es en EE. UU. por defecto. ZDR, BAA y la lista de IPs permitidas son complementos de pago en Scale, incluidos en Enterprise. También existe un modo de credenciales autogestionadas donde pasas los tokens en el momento de ejecución y Composio nunca los almacena ni los refresca (12 apps ya lo requieren). Si nada de eso te vale, Executor.sh mantiene las credenciales en tu host y las inyecta en cada llamada.

¿No inflan 1,500 apps mi ventana de contexto?

No si usas Tool Router. Las herramientas se descubren en ejecución vía COMPOSIO_SEARCH_TOOLS en lugar de cargarse en bloque. Precarga solo las herramientas que más usas en cada ejecución (unas 20 o menos), o usa SESSION_PRESET_DIRECT_TOOLS para agentes acotados. Executor.sh va más allá y colapsa miles de definiciones de herramientas en aproximadamente una herramienta en contexto, algo que vale la pena medir si los tokens son tu cuello de botella.

¿Puedo usar las mismas herramientas en agentes de terminal y Mastra sin duplicar configuración?

Sí. MCP para agentes de CLI (Codex, Claude Code, omp, pi), session.tools() de @composio/mastra para agentes de framework, y las mismas cuentas conectadas detrás de ambos. La única duplicación es el cableado del lado del cliente; la auth y el catálogo de herramientas viven en un solo sitio.

¿Qué se rompe cuando cambian las APIs de Composio?

Cambian los esquemas de herramientas. Se renombraron 1,445 slugs de enums en 37 toolkits y unas 230 herramientas se marcaron como deprecated. Tu deshacer es fijar toolkitVersions en producción y suscribirte a los webhooks de ciclo de vida: composio.connected_account.expired y composio.trigger.disabled te avisan cuando la auth o un trigger mueren en silencio. La retención de logs es de 7 días en Gratis y 30 en Scale, así que exporta si depuras desde logs.

¿Cómo mantengo la factura predecible?

Quédate en el plan Gratis con tope duro, o pon topes de gasto en Scale. Registra tus propias apps OAuth para que aplique la cuota gratis completa (las apps gestionadas topan en 20K de 100K llamadas). Evita las herramientas premium (Exa, Tavily, Browser Use, Veo) o ponles tope. Indica en los prompts que los agentes no reconsulten para verificar, cachea resultados de 30 a 60 segundos y prefiere la ejecución dentro de una Session sobre la directa. Revisa el panel de medición de uso tras la primera semana real de agentes.

¿Puedo autoalojar Composio?

No como operador en solitario. El autoalojamiento es solo Enterprise y requiere pasar por ventas, y la petición de la comunidad (issue #291) lleva abierta desde 2024. Esta misma noche puedes autoalojar Executor.sh (MIT, Docker o Cloudflare Workers) o ACI.dev (Apache-2.0, Docker+Postgres+Redis). El recorrido completo de Docker y Dokploy está en mi comparativa de Executor.sh vs Composio.