Si trabajas con Codex CLI de OpenAI y necesitas que tu agente lea y responda WhatsApp Business, basta con agregar Aurora MCP a tu archivo ~/.codex/config.toml. Aurora expone un servidor MCP en https://developers.aurorainbox.com/mcp con 30+ herramientas (buscar chats, enviar mensajes, crear contactos, mover oportunidades, registrar webhooks) que Codex consume nativamente. Solo necesitas un workspace de Aurora Inbox, una clave ak_live_* del Developer Portal y un bloque de 5 líneas en TOML. Esta guía cubre el setup completo.
Requisitos previos
Antes de tocar el config, asegúrate de tener:
- Workspace de Aurora Inbox activo (el trial gratuito sirve para validar el flujo completo).
- Número de WhatsApp Business conectado en Aurora (vía OAuth con Meta o registro manual).
- Codex CLI instalado:
npm install -g @openai/codexo el instalador concurlque provee OpenAI. Verifica concodex --version. - Cuenta de OpenAI con acceso a GPT-5 u otro modelo de la serie o, conectada en Codex (
codex login). - Clave Platform API
ak_live_*generada en el Developer Portal de Aurora (siguiente paso).
Codex CLI corre en macOS, Linux y Windows (WSL2 recomendado). El config TOML vive siempre en ~/.codex/config.toml.
Paso 1: Generar la clave de Aurora
- Entra a tu workspace en
app.aurorainbox.com. - Go to Integraciones → Developer Portal (URL directa: https://app.aurorainbox.com/integrations/developer-portal).
- Click en Generar nueva clave. Dale un nombre descriptivo (ej.
codex-cli-laptop-alex). - Copia la clave — empieza con
ak_live_…. Solo se muestra una vez; si la pierdes, debes generar otra.
La clave queda scoped a un solo tenant (un workspace de Aurora) con scope aurora.api.platform. Cualquier acción que ejecute Codex se hace con la identidad de tu workspace y queda registrada en el audit log con el keyId que la originó.
Paso 2: Agregar Aurora MCP a Codex
Abre ~/.codex/config.toml (créalo si no existe) y agrega este bloque:
[mcp_servers.aurora]
url = "https://developers.aurorainbox.com/mcp"
transport = "http"
[mcp_servers.aurora.headers]
Authorization = "Bearer ak_live_REEMPLAZA_TU_CLAVE"
El nombre aurora es arbitrario — es como Codex se referirá al servidor internamente. Si manejas varios workspaces puedes registrar aurora-prod and aurora-staging con sus claves respectivas.
Si prefieres no editar TOML a mano, Codex CLI tiene un shortcut:
codex mcp add aurora \
--url https://developers.aurorainbox.com/mcp \
--header "Authorization: Bearer ak_live_REEMPLAZA_TU_CLAVE"
Verifica que quedó registrado:
codex mcp list
Deberías ver aurora con estado connected y la lista de herramientas disponibles. Si aparece failed, revisa que la clave esté completa, sin espacios extra, y que empiece exactamente con ak_live_.
Paso 3: Probar la conexión
Abre Codex CLI en cualquier directorio y pídele algo simple:
> Lista los primeros 5 contactos de mi cuenta de Aurora Inbox.
Codex va a llamar a la herramienta list_contacts y devolver un array con id, name, phone, email, companyName. Si la respuesta llega con datos reales de tu workspace, el setup funciona y ya puedes pasar a prompts más interesantes.
Tip: la primera vez Codex puede pedirte confirmación antes de invocar cada tool MCP nueva. Acepta y opcionalmente marca "always allow" para herramientas idempotentes como list_contacts either search_chats.
Qué herramientas expone Aurora MCP
Aurora MCP cubre las 10 áreas funcionales del producto. Cada herramienta refleja 1:1 un endpoint REST de la Platform V1 API.
| Categoría | Herramientas representativas | Caso de uso |
|---|---|---|
| Chats | search_chats, get_chat, create_chat, assign_chat_agents, set_chat_owner |
Triage de bandeja, asignación a agentes |
| Messages | send_message (1 msg/seg por tenant), notas internas con note=true |
Respuestas, follow-ups, comentarios para el equipo |
| Chatbots | start_chatbot, stop_chatbot, list_chatbots |
Activar workflows en chats específicos |
| Contacts | list_contacts, get_contact, create_contact, update_contact, upsert_contact, delete_contact |
CRM básico desde el agente |
| Empresas | Tools de Company para listar, consultar y editar | Cuentas B2B |
| Oportunidades | create_opportunity, update_opportunity, delete_opportunity, list_chat_opportunities |
Mover deals en el embudo |
| Channels | Listar y revisar status de WhatsApp Cloud API, WhatsApp Business, Messenger, Instagram | Diagnóstico multi-canal |
| Equipos / Usuarios | Tools de Team y User para invitar, asignar y consultar | Onboarding programático |
| Webhooks | create_webhook (HTTPS, máx. 5/tenant, secret se muestra una sola vez), list_webhooks |
Eventos out-bound a tu infraestructura |
| Diagnóstico | health, whoami |
Validar conectividad y permisos |
The channelType que aceptan create_chat y herramientas relacionadas son: 0=WhatsApp Cloud API, 1=WhatsApp Business, 2=Messenger, 3=Instagram. create_contact requiere name and phone; upsert_contact está keyed por phone.
Tres prompts de ejemplo end-to-end
Triage matutino
Busca en Aurora todos los chats de WhatsApp sin contestar de las últimas 24 horas.
Para cada uno, lee el último mensaje del cliente y dame un resumen de una línea
y la prioridad (alta/media/baja) basada en si menciona dinero, urgencia o queja.
Codex llama a search_chats(unanswered=true) y luego get_chat(id) por cada uno. Tú obtienes una lista priorizada en lenguaje natural lista para que el agente humano arranque el día.
Crear contacto y abrir oportunidad
Tengo un lead nuevo: Daniela Pérez, +52 81 9876 5432, daniela@empresa.mx,
Empresa "Distribuidora Norte". Créalo en Aurora y abre una oportunidad en el
embudo "Ventas Q3" del equipo de ventas con monto estimado de $120,000 MXN.
Codex encadena upsert_contact → create_chat (canal WhatsApp Cloud) → create_opportunity → update_opportunity(dealAmount=120000). Todo desde la terminal sin abrir la UI de Aurora.
Follow-up masivo
Busca los chats sin respuesta del cliente de hace más de 72 horas.
A cada uno mándale un mensaje de follow-up corto y amable preguntando si
todavía necesita ayuda. Espera 1 segundo entre envíos para respetar el rate limit.
Codex respeta automáticamente el rate limit de send_message (1 mensaje/segundo por tenant). Si lo excede, recibe Rate limit exceeded… retry after 1s y se pausa solo.
Solución de problemas
Error 401 Unauthorized
La clave no se pegó completa o tiene espacios o saltos de línea. Vuelve a generar y pégala con cuidado dentro de las comillas dobles del TOML. Recuerda: la clave debe empezar exactamente con ak_live_. Si copias del Developer Portal, evita seleccionar el espacio que a veces queda al final.
Error 403 Forbidden en herramientas específicas
Algunas herramientas requieren roles adicionales. Por ejemplo, delete_contact necesita el rol Contact Administrator. Revisa los roles del usuario asociado a la clave en Integraciones → Developer Portal → Permisos. La clave hereda los permisos del usuario que la generó.
Las herramientas no aparecen en codex mcp list
Reinicia la sesión de Codex (sal con exit y abre codex de nuevo) — los MCP servers se cargan al inicio. Si persiste, verifica que el endpoint responde:
curl https://developers.aurorainbox.com/.well-known/mcp.json
Debe devolver un JSON con protocolVersion: "2025-03-26" and transport: "streamable-http".
Rate limit en send_message
Aurora limita envíos a 1 mensaje por segundo por tenant para proteger la calidad de número en Meta. Si tu agente quiere mandar 100 mensajes, secuéncialos con 1 segundo de espera (Codex lo hace automáticamente al ver el header de retry) o usa /Platform/V1/Messaging/Bulk por REST (no expuesto vía MCP por diseño).
Cómo lo hace Aurora MCP
A diferencia de pegar la WhatsApp Cloud API directo en function calling de OpenAI, Aurora MCP da:
- Auth simple: una clave
ak_live_*reusa el mismo sistema de Platform API. Sin OAuth de tres patas, sin tokens que expiran cada hora. - Audit log nativo: cada llamada queda registrada en Aurora con el
keyIdque la originó. Sabes qué máquina y qué desarrollador hizo cada acción. - Rate limits por tenant: tu agente no puede degradar la calidad de número en Meta enviando demasiado rápido; Aurora aplica el throttling antes de tocar Meta.
- Multi-channel: la misma herramienta funciona para WhatsApp Cloud API, WhatsApp Business, Messenger e Instagram — el agente elige el canal con
channelType. - CRM detrás: cada chat ya está vinculado a un contacto y puede generar oportunidades — no es solo "enviar mensaje suelto".
Plan recomendado para empezar a usar Codex con Aurora: Aurora IA $179 USD/mes ($3,200 MXN) que incluye GPT-5, RAG nativo, agendamiento embarcado y MCP server sin restricción.
Empieza tu prueba gratuita y conecta Codex CLI en 5 minutos.
Frequently Asked Questions
¿Aurora MCP es gratis?
El servidor MCP está incluido en cualquier plan pagado de Aurora Inbox (CRM $99 USD / $1,800 MXN, IA $179 USD / $3,200 MXN, IA Plus $329 USD / $6,000 MXN). El trial de 14 días también lo incluye sin restricción ni tarjeta de crédito.
¿Codex CLI corre en macOS, Linux y Windows?
Sí. El binario tiene builds nativos para macOS (Intel + Apple Silicon), Linux x64/arm64 y Windows. En Windows, OpenAI recomienda WSL2 para mejor compatibilidad con shells y herramientas de dev. El archivo ~/.codex/config.toml vive en el HOME del usuario de Codex en cualquier plataforma.
¿Mi clave queda visible en logs de Codex CLI?
Codex maskea headers Authorization en su log de debug por default. Aún así, trata ak_live_* como password — no la commitees a git, no la pegues en issues públicos. El archivo ~/.codex/config.toml debe tener permisos 600 (chmod 600 ~/.codex/config.toml en macOS/Linux).
¿Aurora soporta multi-tenant en Codex?
Cada clave es scoped a un tenant. Si manejas varios workspaces de Aurora (cliente A, cliente B, staging propio), genera una clave por workspace y registra cada uno como un MCP server distinto en el TOML: [mcp_servers.aurora-clienteA], [mcp_servers.aurora-clienteB]. Codex te dejará elegir o invocar el correcto por nombre.
¿Qué pasa si OpenAI o Anthropic actualizan el protocolo MCP?
Aurora soporta la versión 2025-03-26 (la spec estable adoptada por OpenAI y Anthropic) sobre transporte streamable-http. Las versiones futuras se agregan manteniendo backward-compat según el spec oficial. No tienes que tocar tu config cuando subimos versión menor.
¿Puedo usar Codex y otros agentes (Claude Code, Cursor) sobre la misma cuenta de Aurora?
Sí, simultáneamente. Misma clave o claves separadas — tú decides. La misma instancia de Aurora MCP recibe llamadas de Codex, Claude Code, Cursor, Claude Desktop o cualquier otro cliente compatible sin conflictos. Cada cliente tiene un setup ligeramente distinto — revisa nuestras guías para Claude Code, Claude Desktop, Cursor and VS Code Copilot. Si quieres profundizar en el protocolo, lee qué es MCP y cómo conecta IA con WhatsApp o explora 10 casos de uso de agentes en WhatsApp con Aurora MCP.
