WACrew

Guide

How to build a WhatsApp AI agent with MCP

A practical guide to building a WhatsApp AI agent with the Model Context Protocol. Connect WhatsApp, expose tools over MCP, plug in Claude Code or Cursor, and keep a human in the loop.

Updated 5 min read
On this page
  1. The architecture in one picture
  2. Step 1: pick how you connect to WhatsApp
  3. Step 2: design the tools
  4. Step 3: connect the agent
  5. Step 4: keep a human in the loop
  6. A working example: WACrew
  7. Checklist before going live

Most WhatsApp bots are decision trees. A customer types "1" for billing, "2" for support, and everything else falls through. An AI agent works differently. It reads the conversation, decides what it needs, calls tools to get it, and drafts a reply. The Model Context Protocol (MCP) is the cleanest way to give that agent its tools, because the same server works in Claude Code, Claude Desktop, Cursor and any other MCP client.

This guide walks through the architecture, the tools that matter, how to wire it to an agent, and the guardrails that keep it from embarrassing you in front of a customer.

The architecture in one picture

A WhatsApp agent built on MCP has three layers.

WhatsApp  ──►  collector (connection + history)  ──►  MCP server (tools)  ──►  agent (Claude Code, Cursor...)
  1. The collector keeps a connection to WhatsApp, stores every message and media file, and exposes a way to send.
  2. The MCP server turns that data into tools with clear names and descriptions: read a chat, search history, transcribe a voice note, send a reply.
  3. The agent is the MCP host. The model reads the tool descriptions and decides which ones to call.

Keeping the collector and the MCP server apart matters. The collector has to run 24/7 so nothing is missed. The agent only runs when you or a schedule start it.

Step 1: pick how you connect to WhatsApp

You have two options, and the trade-offs are real.

The official WhatsApp Business Platform (Cloud API). Meta sends incoming messages to your webhook and you reply over HTTP. It is the approved route for businesses, with usage-based pricing and template rules outside the 24-hour window.

WhatsApp Web through a library. Libraries like Baileys link your own account as a companion device over a WebSocket. It handles groups and personal accounts, and it is quick to start. It is also unofficial, so use it only with people who already talk to you and never for bulk messaging.

For the agent, the choice is invisible. What it sees is the set of tools on the MCP server.

Step 2: design the tools

Tool design decides whether the agent is useful. The model chooses tools by reading their names and descriptions, so vague tools get ignored or misused. For a customer-facing agent, a solid starting set covers four jobs:

JobExample tools
Readlist chats, read messages, search history (including transcripts)
Understand mediatranscribe voice notes, describe images, read PDFs
Preparereturn the account's recent writing style and what the customer left open
Actsend a reply, check delivery status, cancel a scheduled send

A few rules that pay off:

  • Return less by default. "Last 50 messages" beats "everything". Large tool outputs crowd the context and cost more.
  • Describe when to use each tool, not only what it does. "Call this before drafting a reply" steers the model better than "returns style data".
  • Make sending reversible. A send tool that schedules a message and returns a ticket, with a separate cancel tool, gives you a window to stop mistakes.

Step 3: connect the agent

Once the MCP server exists, connecting an agent is configuration, not code. In Claude Code, a local stdio server is added with (docs):

claude mcp add whatsapp -- npx -y your-whatsapp-mcp-server

In Cursor, the same server goes in .cursor/mcp.json or ~/.cursor/mcp.json (docs):

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "your-whatsapp-mcp-server"],
      "env": { "API_TOKEN": "${env:WHATSAPP_API_TOKEN}" }
    }
  }
}

From there, prompts like "which clients are waiting for a reply?" or "summarize today's messages in the project group" just work, because the model finds the tools that answer them.

Step 4: keep a human in the loop

The hardest part of a WhatsApp agent is not the model. It is making sure it never sends something you would not have sent. Three layers help:

  1. A send mode per chat. Default every chat to confirm: the agent drafts, you approve. Turn on autonomous sending chat by chat, only where replies are routine.
  2. Deterministic review before sending. Plain rules catch the tells that make text read like a bot: an opening "Great question!", a stock closing that offers more help, em dashes, bullet lists in a chat bubble. The open-source botsmell library does this for English and Portuguese and returns a fix for each hit, which you can feed back to the model.
  3. Human pacing. A long reply that lands two seconds after the customer's message gives the automation away. Delay sends in proportion to length, show "typing", and cancel the send if the customer writes again.

Hand off anything about price, deadlines or complaints to a person.

A working example: WACrew

WACrew is an open-source (Apache 2.0) WhatsApp AI agent built exactly this way. The collector runs on Baileys and stores every chat; a panel shows who is waiting; and the WhatsApp MCP server exposes 36 tools, from ler_mensagens and transcrever to preparar_resposta, responder and cancelar_envio.

The MCP server is published on npm as wacrew-mcp and listed in the official MCP Registry as io.github.sumioshi/wacrew. With the panel running on a server, you connect Claude Code with:

claude mcp add wacrew \
  -e WAC_CLOUD_URL=https://your-panel.example.com \
  -e WAC_CLOUD_USER=admin -e WAC_CLOUD_PASS=change-me \
  -- npx -y wacrew-mcp

Every reply passes a deterministic review before it leaves, each chat has a confirm or autonomous mode, and responder returns a ticket that is delivered at a human pace and cancelled if the customer writes first.

Checklist before going live

  • The collector runs 24/7 with persistent storage for the session.
  • Tools have clear descriptions and bounded outputs.
  • Every chat starts in confirm mode.
  • Replies pass a review step before sending.
  • Pricing, deadlines and complaints go to a person.
  • Every send is logged with what the agent read first.

If you are new to the protocol itself, start with what MCP is. To compare existing servers before building your own, see WhatsApp MCP servers compared.