MCP server documentation

Quick start

1. Create a workspace     →  https://console.whatsmcp.com/register
2. Link a WhatsApp number →  Console → Pair device (scan the QR with your phone)
                             …or, for a Business (official) number: Add a number → Connect with Facebook
3. Give your client       →  https://api.whatsmcp.com/mcp
                             …and sign in when it asks. No key to paste.

For Claude Code that is two commands:

claude mcp add --transport http wamcp https://api.whatsmcp.com/mcp
claude mcp login wamcp

Then ask your agent: “list my WhatsApp accounts and show me the last few messages.”

Clients that cannot sign in — curl, CI, anything without OAuth — take a key in a header instead: mint one, then see Connect your client.

Register

Sign-up is self-serve and free — no card, no sales call.

You give a name and an email address. We send a confirmation link; opening it is where you choose a password. Confirming creates your workspace (tenant) on the free plan and drops you into a short setup wizard that walks the three steps that turn a bare account into a working integration: link a number, mint a key, and — optionally — point a webhook at your endpoint. It is derived from what you have actually done rather than a checklist you tick, so it disappears once you are set up and comes back if you unlink everything.

Everything lives in the console:

Per-number pages (Messages, Contacts, Calls) hang off each account in the same console.

Link a WhatsApp number

A Personal number connects as a linked device, the same mechanism as WhatsApp Web. Your phone stays the primary device and can stay in your pocket afterwards. (For a number on Meta’s WhatsApp Cloud API, see Connect a Business number.)

From the console: open Pair device, then on the handset go to WhatsApp → Settings → Linked devices → Link a device and scan the code.

The code rotates roughly every 20 seconds and the page refreshes itself, so a stale QR never sits there failing to scan. The stepper underneath tracks the whole run: the handset accepts the code (scanned), the device logs in and pulls its history (syncing), and only then is the number ready to use.

From the agent, with the wa_pair_account tool:

// 1. start pairing — returns a QR as a base64 PNG for the user to scan
wa_pair_account()
→ { "pair_id": "…", "state": "qr", "qr_png_base64": "iVBORw0…", "instructions": "…" }

// 2. the code rotates about every 20 seconds — poll for the current one
wa_pair_status({ "pair_id": "…" })
→ { "state": "qr",     "qr_png_base64": "…" }     // show the new image
→ { "state": "paired", "instructions": "Linked. …" }  // done

Once state is paired the number appears in wa_list_accounts and is ready to use. wa_unpair_account disconnects it again.

Connect a Business number

A Business (official) number runs on Meta’s WhatsApp Cloud API instead of as a linked device. It is officially supported by Meta, uses message templates, and pays Meta’s own per-message pricing, which Meta bills to your WhatsApp Business Account.

1. Connect. In the console choose Add a number → Connect with Facebook, then pick or create your WhatsApp Business Account and the number in Meta’s dialog. The number registers on the Cloud API by itself and appears in wa_list_accounts. The same MCP connector serves both kinds of number — nothing changes in your client.

2. Templates. Meta requires a pre-approved template to start a conversation, or to message someone more than 24 hours after they last wrote. Manage them with wa_list_templates, wa_create_template and wa_delete_template; Meta reviews each new one. Send one with wa_send_message:

   wa_send_message({ "account_id": "acct_…", "to": "447700900111",
                     "template": "hello_world", "template_language": "en_US",
                     "template_variables": ["Ada"] })   // fills {{1}}, {{2}}, …

3. The 24-hour window. Within 24 hours of the customer’s last message you can reply with ordinary text and media. Outside it a free-form send is refused, and a template is required.

4. What a Business number cannot do. Groups, channels, contacts, history import, presence, reactions, edits, deletes, blocking and profiles are Personal-only. A tool that needs one of them answers with a backend_capability refusal naming the feature, and wa_list_accounts lists each number’s backend and features up front.

5. Calls. A Business number takes WhatsApp calls on a line of its own. With Calls out on, the line also calls customers, from the Pipedrive call window or a phone on the line, once each customer has allowed your calls. Both are set up in the console, on the number’s SIP trunk page (titled Business calling for a Business number). Over MCP you ask for the permission: create a template with call_permission: true, send it once Meta approves it, and read the customer’s answer as a call_permission message. The calls themselves, in and out, are in wa_list_calls, as a Personal number’s are. Call customers on WhatsApp from your Business number walks through it, with WhatsApp’s limits and what calls cost.

6. Plans. Business numbers have their own tiers on the plans page, each starting with a 7-day free trial.

Create an API key

Optional. A client that can sign in with OAuth never needs one — skip to Connect your client. Keys are for curl, for CI, and for clients that cannot do OAuth.

Console → API keys → Create key.

Keys look like wamcp_live_XXXXXXXXXXXX_… and are shown exactly once — we store only a hash, so a lost key is replaced, never recovered. Mint one key per client or per environment and revoke individually.

The key is the workspace. Every tool is scoped to it: there is no tenant argument to pass and no way for one workspace to reach another’s messages.

Connect your client

Any MCP client that speaks Streamable HTTP will work. There is one endpoint:

Connected with https://app.whatsmcp.com/mcp before? It still works — same server, same tools, same sign-in — so there is nothing to change.

There are two ways to prove who you are against it.

OAuth — recommended, and what every client below does by default. The client reads the server’s own metadata, registers itself, and sends you to the console to approve it. Nothing is pasted anywhere: no key is created, none is stored in a config file, and you can revoke one client without touching the others from Console → Connections.

An API key — Authorization: Bearer <your key>, or x-api-key: <your key> for clients that reserve Authorization for a token they manage themselves. Use it for curl, for CI, and for clients that cannot do OAuth. See Create an API key.

Claude Code

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

Then run /mcp inside Claude Code, pick Authenticate, and sign in in the browser window it opens. claude mcp login wamcp does the same thing from the shell. claude mcp list should then show wamcp connected.

With a key instead, and no sign-in step:

claude mcp add --transport http wamcp https://api.whatsmcp.com/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Claude Desktop and claude.ai

Open Settings → Connectors → Add custom connector, put the endpoint in the URL field, leave Authentication on OAuth, and sign in when Claude asks. The dialog discovers the flow on its own.

The authentication type is fixed when the connector is added. A connector created with a header or an API key never switches itself to OAuth later — delete it and add it again.

To use a key here instead, set Authentication to None and add one entry under Additional request headers:

Paste the key on its own — no Bearer in front of it. Authorization is not offered in that dialog: it is kept for the OAuth token Claude manages itself. Header values are stored once and never shown again, so if the connector will not connect, replace the header rather than trying to read it back — a wrong key and a missing one look identical from the outside.

If you edit the configuration file instead of using the dialog, it has no such restriction:

{
  "mcpServers": {
    "wamcp": {
      "type": "http",
      "url": "https://api.whatsmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

ChatGPT

Turn on Developer mode under Settings → Security and login (availability depends on your ChatGPT plan), then go to Plugins, press +, and give it the endpoint.

OAuth is the only way in here. ChatGPT cannot present a custom API key to an MCP server, so the key path in this page does not apply to it — there is no header field to put one in. The sign-in flow is the whole configuration.

Codex

codex mcp add wamcp --url https://api.whatsmcp.com/mcp

That one command is the whole setup: there is no separate login step. Codex adds the server, sees that it signs in with OAuth (Detected OAuth support. Starting OAuth flow…) and opens the sign-in in your browser; approve it there and the terminal prints Successfully logged in.

To sign in again later — say, after revoking the grant in Console → Connections — run codex mcp login wamcp.

Or write the same server into ~/.codex/config.toml by hand; the URL is all it needs. A server added that way has not signed in yet, so run codex mcp login wamcp once:

[mcp_servers.wamcp]
url = "https://api.whatsmcp.com/mcp"

To use a key instead, keep it in the environment and name the variable when you add the server. Codex then skips the sign-in:

export WHATSMCP_API_KEY=wamcp_live_…
codex mcp add wamcp --url https://api.whatsmcp.com/mcp --bearer-token-env-var WHATSMCP_API_KEY

The same thing in config.toml:

[mcp_servers.wamcp]
url = "https://api.whatsmcp.com/mcp"
bearer_token_env_var = "WHATSMCP_API_KEY"

Codex sends that as Authorization: Bearer …. If you would rather set headers yourself, use http_headers for static values and env_http_headers to pull them from the environment.

Every other client

Clients differ in where they keep configuration, but they all need the same thing: the endpoint added as a remote HTTP (not stdio) server. A client that supports OAuth will find the sign-in flow by itself once it has the URL. One that does not needs the key in Authorization, or in x-api-key where it will not let you set Authorization.

If a client only offers “a command to run”, it does not support remote servers — there is no local process to point it at.

How the OAuth flow works

Worth reading only if you are integrating a client of your own, or wondering what your agent just agreed to. Everything here is standard OAuth 2.1 — no custom handshake.

The server publishes two metadata documents, which is how a client bootstraps with nothing but the endpoint URL:

A client registers itself either by Dynamic Client Registration (RFC 7591, at /oauth/register) or by publishing a Client ID Metadata Document whose URL is its client id — both are supported, and the vendors above use one or the other. Then it is an ordinary authorization-code flow with PKCE (S256 only): you land on the consent page at https://console.whatsmcp.com/oauth/authorize, approve, and the code is exchanged at https://api.whatsmcp.com/oauth/token. Authorization codes are single-use, refresh tokens rotate on every use, and a retired refresh token being replayed revokes the whole grant rather than issuing another. Tokens are bound to this resource (RFC 8707) and revocable at /oauth/revoke (RFC 7009).

Seven scopes are advertised and recorded on each grant:

Scope is recorded, not enforced at the tool layer. Which tools a grant can actually reach is decided by your plan, exactly as it is for an API key. Treat the scope list as a description of what the connection is for, not as a sandbox.

Grants are listed and revocable at Console → Connections. Revoking one there disconnects that client and nothing else.

Check it by hand

curl -s https://api.whatsmcp.com/mcp \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Two things catch people out when driving the endpoint directly:

• The reply may be server-sent-event framed — one data: line per message.
• A tool result is text that is itself JSON, so it is parsed twice.

The endpoint is stateless (MCP 2026-07-28 removed protocol sessions), so it needs no sticky routing and it is safe to call from anywhere.

Tools

46 tools. Which ones appear in tools/list depends on your plan and on the kind of number — a tool your plan does not include is absent, not present-and-refusing. Console → Help lists the set your workspace gets, marked against what your plan includes.

Start with wa_list_accounts. Every other tool takes an account_id from it, and a number is usable only while its status is live (its state then reads connected).

Accounts, pairing and plan

Messaging

Message templates (Business numbers)

Meta requires a pre-approved template to start a conversation from a Business (official) number, or to message someone more than 24 hours after they last wrote. Send an approved one with wa_send_message — see Connect a Business number.

Asking to call. call_permission: true adds WhatsApp’s call permission request to the template: under your text the customer gets Allow and Don’t allow, and can allow calls for 7 days or for good. Meta takes it on MARKETING and UTILITY templates only, and never beside buttons, so a draft with both is refused before it reaches Meta. Leave the body without variables if the Pipedrive call window should be able to send the template too. The answer comes back as a call_permission message.

wa_create_template({ "account_id": "acct_…", "name": "call_ok", "category": "UTILITY",
                     "body": "Can we call you on WhatsApp about your order? You can change this any time.",
                     "call_permission": true })

Message operations

Each of these acts on a message that already exists, so each one takes the message_id that wa_list_messages gave you.

Contacts and profiles

Unlike wa_list_contacts, wa_get_profile asks WhatsApp rather than reading the local store. An empty about or picture means the peer has not shared it with this account, not that they have none.

Blocklist

Both report who, not just a number: each entry carries the number, the name this account’s address book has for them (absent for someone never saved on the phone) and the country the number belongs to. WhatsApp does not record when a contact was blocked, so no date is available.

Groups and channels

Group administration

Every one of these follows WhatsApp’s own rules: a mutation that needs admin fails without it, rather than silently doing nothing.

Calls

AI voice agents (Personal numbers)

Webhooks (paid plans)

Reach for wa_enable_webhook rather than deleting and recreating when you only want deliveries to stop for a while: deleting issues a new secret, and everything verifying the old one breaks.

Contacts

Your agent should not have to make you be the address book. wa_list_contacts reads the contacts synced from the phone the account is linked to, so an agent can turn “message Alice” into a number on its own.

It reads the account’s local contact store. Nothing here talks to WhatsApp: no lookups are performed against the network, and asking is free of any rate cost beyond your plan’s ordinary request throttling.

wa_list_contacts — the whole address book

wa_list_contacts({ "account_id": "acct_…", "limit": 500 })
→ {
    "contacts": [
      { "phone": "447700900111", "name": "Alice Perreira", "name_source": "saved",
        "jid": "[email protected]" },
      { "phone": "447700900222", "name": "Bakery",         "name_source": "business", "jid": "…" },
      { "phone": "447700900333", "name": "dave",           "name_source": "push",     "jid": "…" }
    ],
    "total": 482,
    "next_cursor": "447700900333",
    "has_more": true
  }

Paging is by cursor over a stable order (sorted by phone), so it never repeats or skips a row. Default page 500, maximum 2000.

Searching — find one person

wa_list_contacts({ "account_id": "acct_…", "query": "+44 7700 900111" })

Matching is case-insensitive and ignores punctuation in numbers, so "+44 7700 900111" finds a contact stored as 447700900111. It looks at saved names, business names, the name the contact publishes for themselves, and the number. An empty result means no match — not an error.

Things worth knowing

• A newly linked account starts with an empty address book. Contacts arrive from the phone by app-state sync shortly after linking, so “no contacts” right after pairing is usually “not synced yet”. The tool says so in a note rather than letting an agent report that a customer with 500 contacts has none.
• Only numbers saved on the phone itself are contacts. Someone you have chatted with but never saved has no address-book entry — but they do appear as a peer in wa_list_messages.
• If the number is not working, the read refuses with account_not_connected and the number’s account_status, rather than returning an empty book that reads as “you know nobody”.
• The console shows the same address book per number under Contacts, if you would rather look with your eyes.

Reading incoming messages

The server never pushes to your agent. Nothing can interrupt a model when a message arrives, so your agent reads on its own schedule — and a cursor is what makes that reliable.

wa_list_messages returns messages oldest-first, each with a cursor, plus a next_cursor for the page and has_more. Pass a cursor back as after_cursor to get only what has arrived since — no gaps, no duplicates, even for two messages in the same millisecond, which a timestamp cannot promise.

after = 0
repeat:
    r = wa_list_messages(after_cursor = after)
    for m in r.messages:
        if m.direction == "inbound":
            handle(m)                 # e.g. reply with wa_send_message
    after = r.next_cursor             # advance — only newer rows next time
    if not r.has_more:
        sleep(a while)                # caught up; poll again later

Each row says who and where:

To reply: in a DM send to the peer’s number; in a group or channel send to the chat JID — sending to the individual peer would start a private chat instead.

call_permission is a Business number’s call permission, as a message. A customer’s answer to a request to allow calls arrives inbound, and its text is one of Allowed calls (no expiry), Allowed calls until 23 Oct, Declined calls or Calls permission withdrawn automatically. A request sent from the Pipedrive call window is stored outbound with its own text; one sent as a template reads as template. See Connect a Business number for the calls themselves.

In Claude Code, the /loop command automates exactly this: it polls on a cadence, acts when the message appears, and stops. See running loops with /tasks.

For a one-off catch-up on a single account rather than a poll, wa_get_chat returns recent messages without a cursor.

Stored messages read fine while a number is down, so a read says when one is: wa_list_messages, wa_get_chat and wa_get_message carry account_notices for every number they cover that is not working — its account_id, status, status_reason, since and a message to tell the user. New messages are not arriving on that number until it works again.

Webhooks

If you would rather not poll, wa_set_webhook delivers each inbound message to an HTTPS endpoint as it arrives (paid plans).

{
  "event": "message.inbound",
  "delivery_id": "01JB…",
  "tenant_id": "01JA…",
  "account_id": "01J9…",
  "account_phone": "447700900000",
  "message_seq": 48210,
  "message_id": "3EB0…",
  "chat_jid": "[email protected]",
  "peer": "447700900111",
  "kind": "text",
  "body": "are you open on Sunday?",
  "at": "2026-09-02T14:21:07Z"
}

account_phone is your own number that received the message — what a routing rule, a CRM or a support queue is usually keyed on. message_seq is the same cursor wa_list_messages uses, so a consumer that missed a delivery can reconcile instead of guessing. To read the announced message through the tools, pass its account_id and message_id (or message_seq as cursor) to wa_get_message.

Each request carries:

Verify the signature — recompute HMAC-SHA256(secret, "<unix>" + "." + <raw body>) and compare in constant time, rejecting a stale timestamp:

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = parts["t"], parts["v1"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), sig)

Answer 2xx to acknowledge. One attempt is bounded at 10 seconds; a failure is retried with exponential backoff up to 8 attempts, and answering 410 Gone stops delivery of that message permanently — it is the endpoint saying it is never coming back. Recent attempts and their outcomes are visible in Console → Webhooks.

Sending

wa_send_message({
  "account_id": "acct_…",
  "to": "447700900111",          // international form, digits only — or a …@g.us / …@newsletter JID
  "text": "on my way"
})
→ { "status": "sent", "message_id": "3EB0…", "request_id": "01JB…" }

Attachments ride the same tool. text becomes the caption where one applies:

Check the returned status. The three values mean different things:

An agent that treats queued as failure will send your customer the same message twice.

Groups and channels

Listing groups and channels is part of the read surface. Joining, leaving, messaging and group management require the account to be opted into group and channel messaging on its bridge — ask us to switch it on for a number. Without it the account refuses these calls, and the refusal says so verbatim rather than failing generically.

Group management (wa_create_group, add/remove, promote/demote, delete) follows WhatsApp’s own rules: mutations that need admin fail without it. wa_delete_group removes every other member and then leaves, because WhatsApp has no true delete.

Refusals and error handling

A tool that declines does not raise a protocol error — it returns a structured refusal, so a model can read it and decide what to do:

{
  "refused": true,
  "reason": "account_not_connected",
  "message": "This number is not running because of a problem on our side, not anything you need to fix; try again later.",
  "retry_after_seconds": 60,
  "account_status": "not_running",
  "account_status_reason": "stopped",
  "since": "2026-10-10T19:38:03Z"
}

retry_after_seconds absent or 0 means retrying will not help.

At the transport level: an invalid or revoked key gets 401 (never 500, so a client does not retry a dead credential forever), and the endpoint is rate-limited per source address.

Security model

• The credential is the identity. An API key and an OAuth grant resolve to the same thing: a workspace, decided at the edge before any tool runs. It travels on the request context, never as a tool argument, so there is no field in which one workspace could name another.
• A foreign id reads as “no such account”, not “forbidden” — probing reveals nothing.
• Keys are stored hashed, shown once at creation, and revocable individually.
• OAuth grants are revocable per client from Console → Connections. Authorization codes are single-use and refresh tokens rotate; replaying a retired one revokes the grant rather than issuing another.
• Webhook bodies are signed with HMAC-SHA256 over a timestamped payload.
• Your WhatsApp account remains yours: WhatsMCP is a linked device, and you can remove it at any time from the handset (Settings → Linked devices) or with wa_unpair_account.