A WhatsApp MCP server is the bridge between an AI assistant and your WhatsApp CRM: the assistant asks for a tool, the server makes one checked API call, and the answer comes back into the chat with the assistant. In WACRM that bridge is wacrm-mcp, part of WACRM API & MCP, and it works on your WhatsApp Business number under keys you scope, cap and revoke yourself. This playbook belongs to the WACRM guides for every business that sells online.
What is a WhatsApp MCP server?
It is an MCP server whose tools are WhatsApp CRM actions. The Model Context Protocol, which Anthropic introduced on 25 November 2024, is described by its maintainers as an open-source standard for connecting AI applications to external systems. Claude, ChatGPT, Visual Studio Code and Cursor are among the clients that support it, so one server works with many assistants.
The three parts of an MCP connection
The MCP architecture has three participants:
- Host: the AI application you type into, such as Claude Desktop or Cursor.
- Client: the piece inside the host that keeps one connection to one server.
- Server: the program that offers tools, resources and prompts. wacrm-mcp offers tools only.
Messages between them use JSON-RPC 2.0. A local server talks to its client over standard input and output (stdio); a remote one uses Streamable HTTP. wacrm-mcp is a local stdio server: it runs with Node.js 20 or newer on the computer where your AI client runs, and it reaches WACRM over HTTPS with your API key.
A business number, not a WhatsApp Web session
Many “WhatsApp MCP” projects you find online drive a personal WhatsApp account through a WhatsApp Web session. That is a different thing. wacrm-mcp never touches a phone session: every tool calls the WACRM Core API, which works on the WhatsApp Business Platform number your project is connected to. Your messages, contacts and inbox stay in the CRM your team already uses, and every call goes through the same scope check as any other API request.
Note
In one line: the AI model lives in your client, the business rules live in the WACRM Core API, and wacrm-mcp only translates one tool call into one API call. It holds no business logic of its own.
What can an AI agent do in WACRM through MCP?
It can do what a teammate does in the inbox, within the scopes of its key. The 11 tools fall into five groups: messages, contacts, order updates, the wallet and the inbox.
| Tool | What the agent can do | Scope needed |
|---|---|---|
send_template | Send an approved WhatsApp template to a customer; a retry with the same Idempotency-Key never sends twice | messages:send |
read_conversation | Read the message history with one contact, page by page | contacts:read |
create_contact | Add a contact from a phone number, with an optional name and email | contacts:write |
notify_order | Subscribe your own HTTPS endpoint to message-status updates for order and delivery confirmations | wa_webhooks:write |
wallet_balance | Read the project’s token wallet balance and this cycle’s usage | wallet:read |
list_conversations | List inbox conversations by status, owner, label, search or open window | contacts:read |
assign_conversation | Give up to 20 conversations to a teammate or an AI agent, or clear the owner | inbox:write |
add_note | Add a private note for your team; it is never sent to the customer | inbox:write |
label_conversation | Add or remove labels on up to 20 conversations | inbox:write |
resolve_conversation | Resolve up to 20 conversations; a new customer message reopens one | inbox:write |
inbox_report | Read the daily inbox report by agent, team, channel or label, or the live view | inbox:read |
The tool list and scopes match the wacrm-mcp page, which stays the reference if the list changes. The Workspace’s MCP preset ticks exactly the seven scopes in the right-hand column, and you can untick any of them.
How does one tool call reach WhatsApp?
In five short hops, with two checks before anything happens. You ask your assistant something in plain words, the
model picks a tool, and the client sends a tools/call request to wacrm-mcp.
1 · You ask
”Which chats are still waiting for a reply?“
2 · Model picks a tool
list_conversationswith a status filter.3 · Action authorized
wacrm-mcp asks the Core API to count one action against the key’s cap.
4 · Scope checked
The Core API checks the key’s scope and project, then runs the call.
5 · Result
The list comes back to your assistant, or a template goes out from your number.
Two WhatsApp rules shape what the assistant can send. Meta opens a 24-hour customer service window each time a
customer writes to you; outside it a business can only send template messages, according to Meta’s
pricing documentation. That is why the MCP send tool is
send_template: an approved template is valid at any time. Since 1 July 2025 Meta bills the WhatsApp Business
Platform per delivered message, so each template the assistant sends is a message your business pays Meta for.
When a call fails, the assistant sees why. A missing scope comes back as insufficient_scope, a used-up plan
limit as plan_limit_reached, and rate limiting as an error too. A tool never returns a silent empty result, so
the model cannot mistake “not allowed” for “nothing found”.
How do you keep the agent inside safe limits?
By deciding, per key, what it may touch and how often. These controls sit in the WACRM Core API and the Workspace, not in the assistant, so a prompt cannot talk its way past them:
- Scopes per key. A key carries only the scopes you ticked. A tool whose scope is missing answers
insufficient_scopeinstead of acting. - One project per key. A project key reaches its own project only; asking for another project’s data returns not found.
- A monthly action cap. Set any whole number from 1 to 1,000,000, or leave it empty. Each tool call counts as one action. At the cap, the key list shows “Cap reached” and further calls are refused, and not charged, until you raise the cap or the month resets (UTC).
- A bulk limit of 20.
assign_conversation,label_conversationandresolve_conversationrefuse more than 20 conversations in one call withbulk_requires_approval. Larger clean-ups stay with a person. - Sends that never double.
send_templatealways carries an Idempotency-Key, so a client that retries after a timeout replays the first answer instead of messaging the customer twice. - Revoke in one click. Revoking a key stops that client at once. The AI tools (MCP) page is visible to the project owner only, and its usage card lists recent actions and whether each was allowed or refused.
Note
Keep the key out of the chat. The key is shown once, sits in the client’s config as WACRM_API_KEY, and is
sent only as the Authorization: Bearer header. wacrm-mcp never logs it or echoes it in a tool result, so never
paste it into a prompt.
WhatsApp’s Business Policy also asks a business that automates replies to offer clear escalation paths to a person. An assistant on MCP is an internal helper for your team, so the customer-facing rule is met the usual way: a teammate stays one tap away in the inbox.
Which playbooks work for an online store?
Start with work where a wrong guess costs nothing, then add sends. These four cover most of what a shop asks its assistant, and each one names the tools and scopes it needs, so you can create a key for that job only.
Morning inbox triage
Ask the assistant for every open chat that is still waiting, grouped by topic, with a one-line summary of each. It
calls list_conversations with status open and the open-window filter, reads the threads that need context with
read_conversation, and suggests labels such as “sizing”, “delivery” or “refund”.
You
Which WhatsApp chats are still waiting for us this morning?
Assistant · used list_conversations, read_conversation
- 1. Customer asks if the blue sneakers run small. Suggested label: sizing.
- 2. Customer wants a delivery date for an order placed on Monday. Suggested label: delivery.
- 3. Customer reports a damaged parcel and sent a photo. Needs a person.
Shall I label chats 1 and 2 and add a private note on chat 3 for the team?
Once you agree, label_conversation applies the labels and add_note leaves a private note on the damaged-parcel
chat. Tools and scopes: contacts:read, inbox:write. A restaurant taking delivery orders or a clinic with a
morning queue of booking questions runs the same play.
Order confirmations and delivery status
If your store runs on WooCommerce or Shopify, WACRM
order automation already sends order confirmations from approved templates. The
assistant helps with the exceptions: a confirmation for an order a teammate took by phone, or a delivery-delay
notice. It sends with send_template, and notify_order subscribes your own HTTPS endpoint to message.status
events, so your system learns when each message was delivered or read. Each delivery carries an
X-WACRM-Signature header; the webhooks guide shows how to verify it.
Leads from email and forms
A wholesale enquiry arrives by email, or a contact form lands in your helpdesk. Ask the assistant to add the
person with create_contact and leave a note on what they asked for. Your team then follows up on WhatsApp from
the inbox. Scope: contacts:write. A contact plan limit, when reached, comes back as plan_limit_reached.
A weekly inbox report
Every Monday, ask for last week’s inbox report grouped by agent or by label, and for the live view of chats
waiting right now. inbox_report returns the inbox report as JSON the assistant can summarise; the CSV export
stays in the Workspace. Add wallet_balance to the same prompt to see the token balance and this cycle’s usage before a busy
week. Scopes: inbox:read, wallet:read. Both are read-only, which makes this the safest first job for a new key.
How does MCP differ from the built-in AI agent?
They do different jobs and work well together. The WACRM AI agent talks to your customers: it drafts replies from your catalog in the inbox, waits for approval or sends inside the rules the owner sets, and stops on the AI pause switch. An assistant on MCP works for your team, on your computer, in your own AI client.
| Built-in WACRM AI agent | Your own assistant over MCP | |
|---|---|---|
| Who it talks to | Customers, in the WhatsApp chat | You and your team, in the AI client |
| Where it runs | Inside WACRM | Your MCP client, with wacrm-mcp on the same computer |
| What it sends to WhatsApp | Replies, approval-first or auto-send in the 24-hour window | Approved templates through send_template |
| Typical job | Answer price and stock questions, hand chats to a person | Triage, notes, labels, reports, exception sends |
The two meet in the inbox: assign_conversation can give a conversation to an AI agent or to a teammate. The
ecommerce AI agent playbook covers the customer-facing side in full.
How do you connect your first AI client?
In three steps from the Workspace, with no code:
- Pick your AI client. Open Settings → AI tools (MCP), click Connect a client and choose Claude Desktop, Cursor or another MCP client.
- Create a key with the MCP preset. The seven scopes come ticked. Untick what this job does not need and set a monthly action cap.
- Paste the config. Copy the key once, then the ready-made config:
claude_desktop_config.jsonfor Claude Desktop,.cursor/mcp.jsonfor Cursor, or one command line for other clients. Restart the client and the 11 tools appear.
Our team gets you the wacrm-mcp server files with your Workspace and helps you connect it. MCP actions run on the Corporate and Partner plans; see pricing. For the full walkthrough, including a first API call with curl, follow the API and MCP quickstart. Developers who want the raw endpoints can use the developer reference.
What should you check before an agent acts on its own?
Run this checklist before you give a key the messages:send or inbox:write scope:
- The key is made for one job, with only that job’s scopes ticked.
- A monthly action cap is set, sized to a normal week of that job.
- The templates the assistant may send are approved and named so the model picks the right one.
- Your prompt asks the assistant to confirm with you before any send, label or resolve.
- Someone reads the usage card on the AI tools (MCP) page each week.
- You know where the revoke button is.
Shops that sell through WhatsApp every day can see the full setup on the online shops solution page. To connect your systems and your AI tools, start from WACRM API & MCP; for an agent built around your own workflow, our custom development team builds the connection with you.
