Usar Pymaia desde tu terminal (Claude Code, Codex, Gemini, Cursor, n8n)

Esta página es para conectar Pymaia desde una terminal o una automatización. Si vas a usarlo desde el chat (claude.ai, ChatGPT, Claude Desktop), andá a Usar Pymaia desde tu chat.

Hay dos formas de autenticar, y conviene elegir a conciencia:

	OAuth (tu cuenta)	API key
Cómo entra	Te logueás con tu usuario de Pymaia	Un token que generás en la app
Permisos	Los de tu rol: sólo admin/owner puede dar escritura	Los scopes que le pongas a la key
Para qué sirve	Vos trabajando en tu máquina	Automatizaciones sin persona adelante (n8n, cron, CI)
Dónde se revoca	Ajustes → Conectores IA (conexión)	Ajustes → Conectores IA (key)

Claude Code — por OAuth, sin key

Es el camino corto: no genera ninguna credencial que después haya que cuidar.

claude mcp add --transport http pymaia https://api.pymaia.com/mcp

Después, dentro de Claude Code:

/mcp

Elegí pymaia → Authenticate. Se abre el navegador, entrás con tu cuenta de Pymaia, elegís la organización y volvés. Desde ahí las tools ya están disponibles en la sesión.

Si preferís usar una API key (por ejemplo, para que corra en CI sin una persona adelante), el snippet es el que la app te muestra ya armado en Ajustes → Conectores IA:

claude mcp add pymaia --transport http https://api.pymaia.com/mcp \
  -H "Authorization: Bearer pymaia_TU_KEY"

Con el plugin (más corto)

Hay un plugin oficial que deja el conector configurado y le suma a Claude Code el método de trabajo de Pymaia — qué mirar primero, cómo se cita un número, cuándo un cero no es un cero:

/plugin marketplace add Pymaia-labs/pymaia-claude-plugin
/plugin install pymaia@pymaia

Es el mismo servidor y la misma autorización; te ahorra el comando y trae el método. Un detalle si venías del claude mcp add de arriba: con el plugin las tools cambian de prefijo a mcp__plugin_pymaia_app__*, así que las reglas que tengas en permissions.allow hay que actualizarlas.

Codex

Codex habla MCP y habla OAuth, así que no hace falta ninguna key:

codex mcp add pymaia --url https://api.pymaia.com/mcp
codex mcp login pymaia

--url es lo que le dice a Codex que el servidor es HTTP (streamable) y no un comando local; sin ese flag intenta ejecutar pymaia como programa y falla. El login abre el navegador: entrás con tu cuenta de Pymaia, elegís la organización y volvés.

Para confirmar que quedó:

codex mcp list

Con API key (CI, o un servidor sin navegador)

La key va por variable de entorno, no adentro del archivo de configuración:

export PYMAIA_API_KEY=pymaia_TU_KEY
codex mcp add pymaia --url https://api.pymaia.com/mcp \
  --bearer-token-env-var PYMAIA_API_KEY

Es a propósito: codex mcp add escribe en ~/.codex/config.toml, que es un archivo que la gente versiona. Con el flag, ahí queda el nombre de la variable y no la credencial.

Nota

Sintaxis verificada contra codex-cli 0.133.0. Si tu versión no acepta --url, es anterior a que Codex soportara servidores HTTP: actualizá con npm i -g @openai/codex.

Gemini CLI

Gemini CLI descubre el flujo de autorización solo: ve el 401, lee nuestros .well-known, se registra y abre el navegador. No hace falta ninguna key.

gemini mcp add --transport http --scope user pymaia https://api.pymaia.com/mcp

Después, adentro de Gemini CLI:

/mcp auth pymaia

--transport http no es opcional: sin ese flag el CLI toma la URL como un comando local e intenta ejecutarla, y el error que ves no menciona ni MCP ni la dirección. --scope user lo deja en ~/.gemini/settings.json en vez de atarlo a la carpeta donde estás parado.

Para confirmar: gemini mcp list.

Con API key

gemini mcp add --transport http --scope user pymaia https://api.pymaia.com/mcp \
  -H "Authorization: Bearer pymaia_TU_KEY"

Nota

Verificado el 28/08/2026 contra nuestro servidor con la forma exacta de redirect que usa el CLI (http://localhost:<puerto al azar>/oauth/callback).

Gemini Enterprise

Es otro producto y otra configuración: el administrador agrega el servidor desde Connected apps → Add MCP Server, y ahí piden un client_id y un client_secret propios, porque Gemini Enterprise no usa registro dinámico. Escribinos a info@pymaia.com y te generamos el par para tu organización.

Los datos que te van a pedir son estos:

campo	valor
MCP Server URL	https://api.pymaia.com/mcp
Authorization URL	https://api.pymaia.com/oauth/authorize
Token URL	https://api.pymaia.com/oauth/token
Transporte	StreamableHTTP (el SSE viejo no sirve)

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "pymaia": {
      "url": "https://api.pymaia.com/mcp",
      "headers": { "Authorization": "Bearer pymaia_TU_KEY" }
    }
  }
}

Después: Cursor → Settings → MCP → reload.

n8n y cualquier otro cliente

Para MCP, cualquier cliente que hable MCP sobre HTTP entra con:

URL:    https://api.pymaia.com/mcp
Header: Authorization: Bearer pymaia_TU_KEY

Para n8n suele ser más cómodo el REST, que expone una ruta por tool con el nodo HTTP Request:

POST https://api.pymaia.com/api/v1/get_kpi_summary
Authorization: Bearer pymaia_TU_KEY
Content-Type: application/json

{ "days_back": 7 }

GET https://api.pymaia.com/api/v1/tools lista las tools que tu key puede llamar, y https://api.pymaia.com/docs es el Swagger con el detalle de cada una.

Dónde se genera la key

Ajustes → Conectores IA → Nueva API Key. Elegís los permisos (por default, lectura), le ponés un nombre para reconocerla, y la copiás: se muestra una sola vez. En esa misma pantalla está el snippet listo para pegar según el cliente, con la clave ya adentro, y la lista de keys y conexiones activas con su botón Revocar.

Problemas frecuentes

Código	Qué pasó	Qué hacer
401	El bearer no es válido, o venció. Con OAuth, el token de acceso dura 1 hora y se renueva solo contra el de refresco (30 días): un 401 persistente quiere decir que la conexión se revocó o que el refresco venció.	Con OAuth: reautenticá (/mcp en Claude Code). Con key: revisá que esté completa (empieza con pymaia_) y que no la hayas revocado en Ajustes → Conectores IA.
403	Falta permiso. Con key: le falta el scope que esa tool pide. Con OAuth: tu rol no pudo otorgar escritura — sólo admin/owner puede darle permisos de escritura o aprobación a un conector externo.	Con key: generá una nueva con el scope que falta. Con OAuth: pedile a un admin de la organización que conecte, o hacelo desde la app.
402	Tu organización llegó al tope de gasto de IA de su plan. Sólo lo tocan las tools que ejecutan agentes o tareas (run_agent, run_task); las consultas no.	Esperá al próximo ciclo o pasá a un plan con más margen. El mensaje del error dice cuánto se gastó y contra qué tope.
429	Límite de tasa: por default 60 llamadas por minuto, por tool y por credencial. Las intensivas tienen topes más bajos (entre 3 y 30 por minuto) — por ejemplo las que devuelven el método completo de un playbook.	Esperá un minuto y espaciá las llamadas. Si te choca seguido con una tool de lectura, probablemente estés haciendo en un loop algo que se resuelve con una sola llamada.

Algunas tools no existen desde una conexión OAuth y por eso no aparecen en la lista: aprobar o rechazar acciones, gestionar miembros y accesos, desconectar plataformas, webhooks salientes y use_client. Es a propósito: son operaciones que se hacen en la app, con una credencial de la cuenta. Desde el conector se lee y se propone.

Soporte

Escribinos a info@pymaia.com, o pedí ayuda desde la app (ver Contacto y soporte). Si el problema es de conexión, contanos qué cliente usás, si fuiste por OAuth o por key y el código de error — con eso se resuelve mucho más rápido.