Connect

Connect Codex to WhatsApp

WhatsMCP is a hosted Model Context Protocol server, so Codex connects to it as a remote HTTP server — no plugin to install and no local process to run. Add the endpoint, sign in once, and Codex can send, read and search real WhatsApp messages from the terminal.

Get an API key Open console Read the docs
shell 
codex mcp add wamcp --url https://api.whatsmcp.com/mcp
codex mcp login wamcp
Setup

Add WhatsApp to Codex in 4 steps.

1

Add the MCP server to Codex

Register the remote server, then sign in. codex mcp add writes the entry; codex mcp login runs the OAuth flow in your browser. OAuth support is detected automatically. (Plain codex mcp add expects a stdio command — a remote server needs the --url form shown here.)

shell 
codex mcp add wamcp --url https://api.whatsmcp.com/mcp
# Detected OAuth support. Starting OAuth flow…
codex mcp login wamcp
2

Or write it into config.toml

Prefer editing config by hand? Add the server to ~/.codex/config.toml. auth defaults to "oauth". To use an API key instead, keep it in the environment rather than the file — Codex sends bearer_token_env_var as Authorization: Bearer.

~/.codex/config.toml 
[mcp_servers.wamcp]
url = "https://api.whatsmcp.com/mcp"
auth = "oauth"

# API-key alternative:
# bearer_token_env_var = "WHATSMCP_API_KEY"
3

Connect a WhatsApp number

Create a free workspace, then connect a number. A Personal number pairs by QR: open Pair device in the console and scan the code with your phone (WhatsApp → Settings → Linked devices). WhatsMCP joins as a linked device — your phone stays primary. A Business (official) Cloud API number connects from the console instead; one connector serves both.

console 
Register  →  https://console.whatsmcp.com/register
Personal  →  Console → Pair device → scan the QR
Business  →  Console → Add a number → Connect with Facebook

Send your first message

Ask the agent in plain language — "list my WhatsApp accounts and send a hello to +44 7700 900111". It calls wa_list_accounts for the account id, then wa_send_message, and you are live.

agent 
> wa_send_message({ "account_id": "acct_…", "to": "447700900111", "text": "Hello from WhatsMCP!" })
{ "status": "sent", "message_id": "3EB0…" }
Capabilities

What Codex can do once it is connected.

The connection exposes one toolbelt for the whole account. Ask Codex in plain language and it calls the right tool — starting with wa_list_accounts for the account id every other tool takes.

Send and reply

Send and answer messages as the connected number — text, images, documents and voice notes — in direct chats, groups and channels, with edits and reactions.

Read and search

Page message history by cursor with no gaps or duplicates, catch up on a chat, and resolve "message Alice" against the synced address book.

Handle media

Download received images, documents and audio by message id, and attach files on the way out.

Manage groups

Create groups, add and remove members, promote and demote admins, join by invite link and follow channels.

Inspect calls

Export call history — direction, peer, duration, answered state and codec — for logging or follow-up.

Receive webhooks

Push each inbound message to your own HTTPS endpoint, signed with HMAC-SHA256, instead of polling for it (paid plans).

Trial & limits

Free to start, honest about the rest.

  • Free Personal plan — self-serve, no card, one linked number. Enough to connect a number and drive it from Codex.
  • Business (official) runs on Meta's WhatsApp Cloud API with message templates and the 24-hour window, on a 7-day free trial — same endpoint, same Codex setup.
  • Plan-scoped tools — which tools appear in the client depends on your plan; an excluded tool is absent, not present-and-refusing. Webhooks and higher send caps are on paid plans.
  • Independent integration — not affiliated with or endorsed by Meta. Automating a Personal number carries the usual WhatsApp terms-of-service risk; the number can be rate-limited or blocked. Remove WhatsMCP any time with wa_unpair_account .
FAQ

Connecting Codex to WhatsApp.

Does codex mcp add work with remote servers?

Yes, with the --url form: codex mcp add wamcp --url https://api.whatsmcp.com/mcp. Plain codex mcp add expects a stdio command; WhatsMCP is a remote Streamable-HTTP server, so it is added by URL and authenticated with codex mcp login (OAuth) or an API key in the environment.

Where does Codex store the WhatsMCP configuration?

In ~/.codex/config.toml, under an [mcp_servers.wamcp] table with the url and auth = "oauth". codex mcp add writes it for you; you can also edit the file directly and reload Codex.

What is the WhatsMCP endpoint URL?

The full URL https://api.whatsmcp.com/mcp — the api. host and the /mcp path both matter. Giving a client the bare host (whatsmcp.com, or whatsmcp.com/mcp) is the most common setup failure; it is a remote Streamable-HTTP MCP server, not a stdio command.

Do I need an API key, or is OAuth enough?

OAuth is recommended and is what every supported client does by default — you approve the connection in the browser and nothing is pasted or stored. An API key (wamcp_live_…) over Authorization: Bearer, or x-api-key where a client reserves Authorization for its own token, is the fallback for CLIs, CI and clients that cannot sign in.

Does this use a Personal or a Business WhatsApp number?

Either, through the same endpoint. A Personal number pairs by QR as a linked device (free plan, one number). A Business (official) number runs on Meta's WhatsApp Cloud API, connects from the console, and adds message templates and the 24-hour window on a 7-day free trial. See /whatsapp-business-api for the official path.

Is this an official WhatsApp or Meta product?

No. WhatsMCP is an independent integration, not affiliated with or endorsed by Meta. A Personal number connects as a linked device, the same mechanism as WhatsApp Web, and you can remove it any time from the handset or with wa_unpair_account.

More connectors

Connect another AI client.

Same endpoint, same OAuth sign-in. See the full list.

Connect Grok

Point a Grok-powered agent at a WhatsApp number through the MCP endpoint.

Connect ChatGPT

Add WhatsApp as a ChatGPT connector in Developer mode, over OAuth.

Connect Claude

Add WhatsApp to Claude as a remote MCP connector over OAuth.

Connect Cursor

Add WhatsApp to Cursor so the Agent can read and reply to your chats.

Connect Manus

Connect the Manus AI agent to a WhatsApp number through the MCP endpoint.

Give Codex a number.

Get an API key Open console

Free Personal plan · 7-day free trial for Business (official).