> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/ai-tools/mcp-model-context-protocol.md).

# MCP (Model Context Protocol)

Connect your AI agent — Cursor, Claude Code, Claude Desktop, GitHub Copilot — directly to WhatsApp. With the Whapi MCP server your agent can send messages, manage groups, post to channels, and check channel status by calling real API methods, instead of guessing what the requests should look like.

**You don't need to be a developer.** With MCP connected, you can simply ask your agent to send a message, create a group, or check channel status — it calls the real API and does it. No code involved. And if you *are* building something, the agent can test against the live API as it goes, instead of guessing what requests should look like. Pair it with the Agent Skill so the code it writes is correct too.

The Model Context Protocol itself is an open standard for giving AI agents structured access to tools and APIs through one unified interface.

***

#### Before you start

You need:

* A Whapi.Cloud channel with a WhatsApp number already paired — [panel.whapi.cloud](https://panel.whapi.cloud/dashboard)
* Your **channel token**, copied from the channel page
* Node.js 18 or newer

{% hint style="info" %}
**Use the channel token, not a Partner Token.** The MCP server connects to one specific channel and works with that channel's credentials. The token appears on the channel page only after a WhatsApp number has been paired.
{% endhint %}

#### Quick start

Run the server with your token:

```bash
# macOS / Linux
API_TOKEN="YOUR_TOKEN" npx -y whapi-mcp@latest
```

```powershell
# Windows PowerShell
$env:API_TOKEN="YOUR_TOKEN"; npx -y whapi-mcp@latest
```

In practice you rarely run this by hand — your MCP client starts it for you (see below).

{% hint style="warning" %}
**whapi-mcp is self-hosted.** It runs as a local process on your own machine, launched by your MCP client over stdio. There is no hosted endpoint and no remote URL to connect to — the package has no HTTP or SSE transport. Your channel token never leaves your machine, and the server runs only while your agent is running.

Any environment with Node.js 18+ works — laptop, VM, or a container next to your app — as long as the agent runs there too.
{% endhint %}

#### Connect your agent

Add the server to your client's MCP config, then restart the client.

**Cursor** — `%USERPROFILE%\.cursor\mcp.json` (Windows) or `~/.cursor/mcp.json` (macOS/Linux):

```json
{
  "mcpServers": {
    "whapi-mcp": {
      "command": "npx",
      "args": ["-y", "whapi-mcp@latest"],
      "env": { "API_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). Same structure.

**Claude Code, VS Code and other MCP clients** use the same `mcpServers` block — only the file location differs.

#### Verify the connection

Ask your agent to call `checkHealth` with no arguments. The `status.text` field tells you where the channel stands:

| Status       | Meaning                   | What to do                          |
| ------------ | ------------------------- | ----------------------------------- |
| `AUTH`       | Connected and operational | Ready to use                        |
| `QR`         | Waiting for QR scan       | Open the channel dashboard and scan |
| `INIT`       | Server initializing       | Wait 40–50 seconds                  |
| `LAUNCH`     | Connecting to WhatsApp    | Wait a few seconds                  |
| `STOP`       | Channel deactivated       | Check your subscription             |
| `SYNC_ERROR` | Sync failure              | Log the channel out and reconnect   |

A `404 Channel not found` means the token is wrong, or no number is paired with the channel yet.

#### Tools

The server exposes 165 tools generated from the Whapi OpenAPI spec — messaging, groups, channels, communities, contacts, labels, media, and channel settings. Each tool maps to one API method.

Sending a text message:

```json
name: sendMessageText
arguments: {
  "to": "1234567890@s.whatsapp.net",
  "body": "Hello"
}
```

Chat ID format matters, and getting it wrong is the single most common mistake:

* Personal chat — `<phone_number>@s.whatsapp.net` (digits only, no `+`)
* Group — `<group_id>@g.us`
* WhatsApp Channel (Newsletter) — `<newsletter_id>@newsletter`

#### If your model struggles with 165 tools

Some LLMs slow down or refuse to load an MCP server that exposes a large tool list. `whapi-mcp-optimal` is a slim build with a curated core toolset:

```json
{
  "mcpServers": {
    "whapi-mcp": {
      "command": "npx",
      "args": ["-y", "whapi-mcp-optimal@latest"],
      "env": { "API_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

Use `whapi-mcp@latest` for the full feature set, and `whapi-mcp-optimal@latest` when tool discovery is slow or the model won't start.

***

{% hint style="success" %}
**Install the Agent Skill too**

The MCP server gives your agent access. The **Whapi Agent Skill** gives it the rules — correct Chat ID formats, real parameter names, webhooks instead of polling. Install for every detected agent at once:

```bash
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill
```

Learn more →
{% endhint %}

***

#### Frequently asked

**Can I use this if I don't know how to code?** Yes. You can use MCP without writing anything at all — just ask your agent to send messages or manage groups, and it does it through the API. And if you're vibe coding a real integration, MCP lets the agent verify each call against the live API instead of guessing. Install the Agent Skill alongside it so the code it writes follows the actual API rules.

**Is there a hosted MCP server or a URL I can connect to?** No. `whapi-mcp` is self-hosted and runs locally over stdio. There is no remote endpoint.

**Which token goes in `API_TOKEN`?** The channel token from your channel page. Not a Partner Token.

**Do I need a paid channel?** You can start on the free trial channel — the full API is available, within the trial limits.

**Which agents are supported?** Any MCP-compatible client: Cursor, Claude Code, Claude Desktop, VS Code, GitHub Copilot, Codex and others.