If you're working with OpenAI's Codex CLI and need your agent to read and respond to WhatsApp Business messages, simply add Aurora MCP to your file. ~/.codex/config.tomlAurora exposes an MCP server in https://developers.aurorainbox.com/mcp With 30+ tools (search chats, send messages, create contacts, move opportunities, register webhooks) that Codex consumes natively. All you need is an Aurora Inbox workspace and a key. ak_live_* from the Developer Portal and a 5-line block in TOML. This guide covers the complete setup.
Prerequisites
Before touching the config, make sure you have:
- Aurora Inbox Workspace active (the free trial It serves to validate the entire flow).
- WhatsApp Business number connected in Aurora (via OAuth with Meta or manual registration).
- Codex CLI installed:
npm install -g @openai/codexor the installer withcurlprovided by OpenAI. Verify withcodex --version. - OpenAI account with access to GPT-5 or another model in the series or, connected in Codex (
Codex login). - Key Platform API
ak_live_*generated in the Aurora Developer Portal (next step).
Codex CLI runs on macOS, Linux, and Windows (WSL2 recommended). The TOML config file always resides in ~/.codex/config.toml.
Step 1: Generate the Aurora key
- Enter your workspace at
app.aurorainbox.com. - Go to Integrations → Developer Portal (Direct URL: https://app.aurorainbox.com/integrations/developer-portal).
- Click on Generate new keyGive it a descriptive name (e.g.
codex-cli-laptop-alex). - Copy the key — it starts with
ak_live_…It is only displayed once; if you lose it, you must generate another one.
The key is scoped to a single tenant (an Aurora workspace) with scope aurora.api.platformAny action that Codex performs is done using your workspace identity and is recorded in the audit log. keyId that originated it.
Step 2: Add Aurora MCP to Codex
Open ~/.codex/config.toml (create it if it doesn't exist) and add this block:
[mcp_servers.aurora] url = "https://developers.aurorainbox.com/mcp" transport = "http" [mcp_servers.aurora.headers] Authorization = "Bearer ak_live_REEMPLAZA_TU_CLAVE"
The name Aurora It's arbitrary—it's how Codex will refer to the server internally. If you manage multiple workspaces, you can register aurora-prod and aurora-staging with their respective keys.
If you prefer not to edit TOML manually, Codex CLI has a shortcut:
codex mcp add aurora \ --url https://developers.aurorainbox.com/mcp \ --header "Authorization: Bearer ak_live_REEMPLAZA_TU_CLAVE"
Verify that it was recorded:
Codex MCP list
You should see Aurora with state connected and the list of available tools. If it appears failedCheck that the key is complete, without extra spaces, and that it starts exactly with ak_live_.
Step 3: Test the connection
Open Codex CLI in any directory and ask it for something simple:
> List the first 5 contacts from my Aurora Inbox account.
Codex is going to call the tool list_contacts and return an array with id, yam, phone, e-mail, companyNameIf the response comes with real data from your workspace, the setup works and you can move on to more interesting prompts.
Tip: The first time you use Codex, it may ask for confirmation before invoking each new MCP tool. Accept, and optionally check "always allow" for idempotent tools such as list_contacts either search_chats.
What tools does Aurora MCP offer?
Aurora MCP covers all 10 functional areas of the product. Each tool mirrors a Platform V1 API REST endpoint 1:1.
| Category | Representative tools | Use case |
|---|---|---|
| Chats | search_chats, get_chat, create_chat, assign_chat_agents, set_chat_owner |
Tray triage, agent assignment |
| Messages | send_message (1 ms/sec per tenant), internal notes with note=true |
Responses, follow-ups, and feedback for the team |
| Chatbots | start_chatbot, stop_chatbot, list_chatbots |
Activate workflows in specific chats |
| Contacts | list_contacts, get_contact, create_contact, update_contact, upsert_contact, delete_contact |
Basic CRM from the agent |
| Companies | Company Tools for listing, querying, and editing | B2B Accounts |
| Opportunities | create_opportunity, update_opportunity, delete_opportunity, list_chat_opportunities |
Moving deals through the funnel |
| Channels | List and review the status of WhatsApp Cloud API, WhatsApp Business, Messenger, and Instagram. | Multi-channel diagnostics |
| Equipment / Users | Team and User tools for inviting, assigning, and querying | Programmatic onboarding |
| Webhooks | create_webhook (HTTPS, max. 5/tenant, secret is shown only once), list_webhooks |
Outbound events to your infrastructure |
| Diagnosis | health, whoami |
Validate connectivity and permissions |
The channelType that accept create_chat and related tools are: 0=WhatsApp Cloud API, 1=WhatsApp Business, 2=Messenger, 3=Instagram. create_contact requires yam and phone; upsert_contact is keyed by phone.
Three example end-to-end prompts
Morning triage
Search Aurora for all unanswered WhatsApp chats from the last 24 hours. For each one, read the customer's last message and give me a one-line summary and the priority (high/medium/low) based on whether it mentions money, urgency, or a complaint.
Codex calls for search_chats(unanswered=true) and then get_chat(id) for each one. You get a prioritized list in natural language ready for the human agent to start the day.
Make contact and open opportunity
I have a new lead: Daniela Pérez, +52 81 9876 5432, daniela@empresa.mx, Company "Distribuidora Norte". Create this lead in Aurora and open an opportunity in the "Q3 Sales" funnel of the sales team with an estimated amount of $120,000 MXN.
Codex chains upsert_contact → create_chat (WhatsApp Cloud channel) → create_opportunity → update_opportunity(dealAmount=120000)All from the terminal without opening the Aurora UI.
Massive follow-up
Look for unanswered chats from customers older than 72 hours. Send each one a short, friendly follow-up message asking if they still need help. Wait 1 second between messages to respect the rate limit.
Codex automatically respects the rate limit of send_message (1 message/second per tenant). If it exceeds this, you receive Rate limit exceeded… retry after 1s and it pauses on its own.
Troubleshooting
Error 401 Unauthorized
The key was not pasted completely or contains spaces or line breaks. Regenerate it and paste it carefully inside the double quotes of the TOML. Remember: the key must start exactly with ak_live_If you copy from the Developer Portal, avoid selecting the space that sometimes remains at the end.
Error 403 Forbidden in specific tools
Some tools require additional roles. For example, delete_contact You need the Contact Administrator role. Check the user roles associated with the key in Integrations → Developer Portal → PermissionsThe key inherits the permissions of the user who generated it.
The tools do not appear in Codex MCP list
Restart your Codex session (exit with exit and open codex (again) — the MCP servers load at startup. If the problem persists, verify that the endpoint is responding:
curl https://developers.aurorainbox.com/.well-known/mcp.json
It should return a JSON with protocolVersion: "2025-03-26" and transport: "streamable-http".
Rate limit in send_message
Aurora limits sending to 1 message per second per tenant to protect number quality in Meta. If your agent wants to send 100 messages, sequence them with a 1-second delay (Codex does this automatically when it sees the retry header) or use /Platform/V1/Messaging/Bulk via REST (not exposed via MCP by design).
How Aurora MCP does it
Unlike directly pasting the WhatsApp Cloud API into OpenAI function calling, Aurora MCP provides:
- Simple Auth: a key
ak_live_*It reuses the same Platform API system. No three-legged OAuth, no tokens that expire every hour. - Native audit logEach call is recorded in Aurora with the
keyIdthat originated it. You know which machine and which developer performed each action. - Rate limits per tenantYour agent cannot degrade the number quality in Meta by sending too quickly; Aurora applies throttling before touching Meta.
- Multi-channelThe same tool works for WhatsApp Cloud API, WhatsApp Business, Messenger, and Instagram — the agent chooses the channel with
channelType. - CRM behindEach chat is already linked to a contact and can generate opportunities — it's not just "sending a random message".
Recommended plan to start using Codex with Aurora: Aurora IA $179 USD/month ($3,200 MXN) which includes GPT-5, native RAG, onboard scheduling and unrestricted MCP server.
Start your free trial and connect Codex CLI in 5 minutes.
Frequently Asked Questions
Is Aurora MCP free?
The MCP server is included in any paid Aurora Inbox plan (CRM $99 USD / $1,800 MXN, IA $179 USD / $3,200 MXN, IA Plus $329 USD / $6,000 MXN). The 14-day trial also includes it with no restrictions or credit card required.
Does Codex CLI run on macOS, Linux, and Windows?
Yes. The binary has native builds for macOS (Intel + Apple Silicon), Linux x64/arm64, and Windows. On Windows, OpenAI recommends WSL2 for better compatibility with shells and development tools. The file ~/.codex/config.toml It lives in the Codex user's HOME on any platform.
Is my key visible in Codex CLI logs?
Codex masks headers Authorization in its default debug log. Even so, it tries ak_live_* as a password — don't commit it to Git, don't paste it into public issues. The file ~/.codex/config.toml You must have permits 600 (chmod 600 ~/.codex/config.toml on macOS/Linux).
Does Aurora support multi-tenant in Codex?
Each key is scoped to one tenant. If you manage multiple Aurora workspaces (client A, client B, your own staging), generate one key per workspace and register each one as a separate MCP server in TOML. [mcp_servers.aurora-clienteA], [mcp_servers.aurora-clienteB]Codex will let you choose or invoke the correct one by name.
What happens if OpenAI or Anthropic update the MCP protocol?
Aurora supports version 2025-03-26 (the stable spec adopted by OpenAI and Anthropic) on transport streamable-httpFuture versions are added while maintaining backward compatibility according to the official specYou don't need to touch your config when we upload a minor version.
Can I use Codex and other agents (Claude Code, Cursor) on the same Aurora account?
Yes, simultaneously. Same key or separate keys—it's up to you. The same Aurora MCP instance receives calls from Codex, Claude Code, Cursor, Claude Desktop, or any other compatible client without conflicts. Each client has a slightly different setup—check our guides for details. Claude Code, Claude Desktop, Cursor and VS Code CopilotIf you want to learn more about the protocol, read on. What is MCP and how does AI connect with WhatsApp? or explore 10 Use Cases for Agents in WhatsApp with Aurora MCP.
