Connect WhatsApp to Codex CLI
OpenAI's Codex CLI reads MCP servers from its config file and can send the key from an environment variable, so the key never sits in the file itself.
Once connected, Codex can look up contacts, follow broadcast delivery or prepare template drafts as part of a terminal task.
Before you start#
- A SheetWA workspace with a WhatsApp number connected through the WhatsApp API.
- An API Growth or API Max plan, or the 7-day free trial.
- An MCP key from the workspace owner or an admin, made under MCP Server in the dashboard.
New to keys? See how to create one.
Add SheetWA to Codex CLI#
- 1Add this block to your Codex config.
- 2Export SHEETWA_API_KEY in your shell before you start Codex.
toml~/.codex/config.toml
[mcp_servers.sheetwa]
url = "https://backend.sheetwa.com/api/v3/mcp"
bearer_token_env_var = "SHEETWA_API_KEY"Replace sk_live_your_key_here with your key. The server URL is https://backend.sheetwa.com/api/v3/mcp.
Check it works#
- 1Export the key in your shell first: export SHEETWA_API_KEY=your key.
- 2Start Codex and ask: "Is my WhatsApp number connected?"
- 3Codex should call waca_connection_status and answer with your number.
Things to try#
- "Show my unread WhatsApp chats and summarise them."
- "Find contacts tagged VIP who have not messaged in 30 days."
- "Which of my templates are approved, and what placeholders do they need?"
- "How did yesterday's broadcast do? List the failed numbers."
Codex CLI picks the right tools on its own. See the tools.
If something goes wrong#
- Codex says the key was refused
- Check SHEETWA_API_KEY is exported in the same shell you start Codex from.
- The server does not load
- Check the [mcp_servers.sheetwa] block is valid TOML and the URL ends in /api/v3/mcp.
- Every call answers PLAN_LIMIT_REACHED
- MCP is included in API Growth and API Max. A workspace on API Lite needs to upgrade first.