---
title: "MCP server"
description: "Let AI agents operate your WhatsApp numbers through MCP."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt
> Use this file to discover all available pages before exploring further.

Project MCP gives AI agents live tools to send messages, read conversations, manage templates, and configure webhooks on your WhatsApp numbers.

Use it when an MCP-capable agent should operate a WhatsApp number without shell access — read inbound messages, send replies, manage templates, configure webhooks, and inspect channels.

**Endpoint:**

```text
https://api.wazapin.com/mcp
```

**Discovery (no auth):** `GET https://api.wazapin.com/.well-known/wazapin-mcp.json` — tool names, actions, and auth headers.

## API key scopes (MCP)

Optional JSON scopes on the API key restrict MCP tools:

| Scope | Allows |
| ----- | ------ |
| `*` or `mcp:*` | All MCP tools |
| `mcp:read` | `status`, `search_docs`, `help`, `list`, `get` |
| `mcp:write` | `send`, `create`, `update`, `mark_read` (and read) |
| `mcp:destructive` | `webhooks` `delete` |

Empty scopes = no MCP restriction (full access still limited by Casbin on REST).

## Authentication

Choose the auth option your MCP client supports:

- **API key (recommended):** create an organization API key in the [dashboard](https://app.wazapin.com) and pass it as a header. The key must start with `wzp_`. Organization context is inferred from the key.
- **Session bearer:** use a dashboard session token as `Authorization: Bearer …` when your client already has a logged-in session with an active organization.

Both options expose the same Project MCP tools when the caller is authorized.

**Accepted API key headers:**

```http
Authorization: Bearer YOUR_API_KEY
```

```http
X-Api-Key: YOUR_API_KEY
```

Use `Authorization: Bearer` for bearer-token clients. Use `X-Api-Key` when your MCP client lets you configure custom headers.

## Connect

### API key

Set your API key:

```bash
export WAZAPIN_API_KEY="wzp_your_key"
```

### Claude Code

```bash
claude mcp add --transport http wazapin https://api.wazapin.com/mcp \
  --header "X-Api-Key: $WAZAPIN_API_KEY"
```
### Cursor

```json
{
  "mcpServers": {
"wazapin": {
  "url": "https://api.wazapin.com/mcp",
  "headers": {
    "X-Api-Key": "${env:WAZAPIN_API_KEY}"
  }
}
  }
}
```
### Grok / generic HTTP MCP

```json
{
  "mcpServers": {
"wazapin": {
  "url": "https://api.wazapin.com/mcp",
  "headers": {
    "Authorization": "Bearer ${env:WAZAPIN_API_KEY}"
  }
}
  }
}
```

### Use Authorization Bearer instead

Swap the header if your client prefers bearer auth:

```json Cursor
{
  "mcpServers": {
"wazapin": {
  "url": "https://api.wazapin.com/mcp",
  "headers": {
    "Authorization": "Bearer ${env:WAZAPIN_API_KEY}"
  }
}
  }
}
```

## Tools

Project MCP exposes grouped tools. Most tools accept an `action` and `params`.

| Tool | Actions |
| ---- | ------- |
| `status` | Shows auth, organization context, channel count, and next steps |
| `search_docs` | Points to the Wazapin docs index (`llms.txt`) for documentation lookup |
| `channels` | `help`, `list`, `get` |
| `conversations` | `help`, `list`, `get` |
| `messages` | `help`, `list`, `get`, `send`, `mark_read` |
| `templates` | `help`, `list`, `get` |
| `webhooks` | `help`, `list`, `create`, `update`, `delete` |
| `contacts` | `help`, `list`, `get` |

Use `action: "help"` on grouped tools to list actions and see example payloads.

## Examples

Ask your agent to check setup:

```text
Use the wazapin MCP server to check my project status and tell me the next action.
```

Ask your agent to read and send WhatsApp messages:

```text
Use wazapin conversations with action=list to list recent open conversations, then messages with action=list for the latest thread.
```

```text
Use wazapin messages with action=send to send "Hello from Wazapin" to +6281234567890 from my connected channel.
```

Configure outbound webhooks:

```text
Use wazapin webhooks with action=list, then explain which event types I can subscribe to.
```

## Project MCP vs docs

| Surface | URL | Use it for |
| ------- | --- | ---------- |
| Project MCP | `https://api.wazapin.com/mcp` | Operating WhatsApp numbers with an API key or session |
| Docs index | `https://docs.wazapin.id/llms.txt` | Documentation discovery for agents and humans |
| REST API | `https://api.wazapin.com` | Full programmatic control (see [API overview](/api/overview)) |

Use the [REST API](/api/overview) or [TypeScript SDK](/sdk/typescript) when your agent has HTTP or code access. Use Project MCP when your agent supports MCP and should call Wazapin tools directly.

Source: https://docs.wazapin.id/mcp/server/index.mdx