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

# MCP server

> Let AI agents operate your WhatsApp numbers through MCP.

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 provision new numbers.

Endpoint:

```text theme={null}
https://api.kapso.ai/mcp
```

## Authentication

Choose the auth option your MCP client supports:

* Browser sign-in: configure the MCP URL, sign in to Kapso, and choose one project.
* API key: create a project API key in Kapso and pass it as a header.

Both options give the agent access to the same Project MCP tools.

Accepted API key headers:

```http theme={null}
Authorization: Bearer YOUR_PROJECT_API_KEY
```

```http theme={null}
X-API-Key: YOUR_PROJECT_API_KEY
```

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

## Connect

### Browser sign-in

For clients that support browser sign-in, configure only the MCP URL.

<CodeGroup>
  ```bash Codex theme={null}
  codex mcp add kapso --url https://api.kapso.ai/mcp
  codex mcp login kapso
  ```

  ```bash Claude Code theme={null}
  claude mcp add --transport http kapso https://api.kapso.ai/mcp
  # Then run inside Claude Code:
  /mcp
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "kapso": {
        "url": "https://api.kapso.ai/mcp"
      }
    }
  }
  ```
</CodeGroup>

When Kapso opens in the browser, sign in and select the project the client should use.

### API key

Set your project API key:

```bash theme={null}
export KAPSO_API_KEY="your_project_api_key"
```

<CodeGroup>
  ```bash Codex theme={null}
  codex mcp add kapso --url https://api.kapso.ai/mcp --bearer-token-env-var KAPSO_API_KEY
  ```

  ```bash Claude Code theme={null}
  claude mcp add --transport http kapso https://api.kapso.ai/mcp \
    --header "Authorization: Bearer $KAPSO_API_KEY"
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "kapso": {
        "url": "https://api.kapso.ai/mcp",
        "headers": {
          "Authorization": "Bearer ${env:KAPSO_API_KEY}"
        }
      }
    }
  }
  ```
</CodeGroup>

### Use X-API-Key instead

Codex CLI has no `--header` flag, so X-API-Key goes in `~/.codex/config.toml`. For Cursor and Claude Code, just swap the header.

<CodeGroup>
  ```toml Codex theme={null}
  [mcp_servers.kapso]
  url = "https://api.kapso.ai/mcp"
  env_http_headers = { "X-API-Key" = "KAPSO_API_KEY" }
  ```

  ```bash Claude Code theme={null}
  claude mcp add --transport http kapso https://api.kapso.ai/mcp \
    --header "X-API-Key: $KAPSO_API_KEY"
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "kapso": {
        "url": "https://api.kapso.ai/mcp",
        "headers": {
          "X-API-Key": "${env:KAPSO_API_KEY}"
        }
      }
    }
  }
  ```
</CodeGroup>

## Tools

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

| Tool                     | Actions                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `status`                 | Shows auth, project status, customer count, WhatsApp number count, and next steps       |
| `search_docs`            | Searches Kapso and WhatsApp docs                                                        |
| `customers`              | `help`, `list`, `get`, `create`, `update`, `delete`                                     |
| `setup_links`            | `help`, `list`, `create`, `update`, `revoke`                                            |
| `whatsapp_numbers`       | `help`, `list`, `get`, `resolve`, `health`, `start_setup`, `create`, `update`, `delete` |
| `whatsapp_conversations` | `help`, `list`, `get`, `set_status`                                                     |
| `whatsapp_messages`      | `help`, `list`, `get`, `send`, `mark_read`                                              |
| `whatsapp_templates`     | `help`, `list`, `get`, `create`                                                         |
| `whatsapp_webhooks`      | `help`, `list`, `get`, `create`, `update`, `delete`                                     |

Use `action: "help"` on grouped tools to get required params, optional params, and examples.

## Examples

Ask your agent to check setup:

```text theme={null}
Use the kapso MCP server to check my project status and tell me the next action.
```

Ask your agent to create a setup link:

```text theme={null}
Use kapso setup_links with action=create for the default customer, then return the setup URL.
```

Ask your agent to read and send WhatsApp messages:

```text theme={null}
Use kapso whatsapp_conversations to list recent active conversations, then use whatsapp_messages to read the latest inbound messages.
```

```text theme={null}
Use kapso whatsapp_messages with action=send to send "Hello from Kapso" to +15551234567 from my connected WhatsApp number.
```

## Project MCP vs Docs MCP

| Server      | Endpoint                    | Use it for                                                    |
| ----------- | --------------------------- | ------------------------------------------------------------- |
| Project MCP | `https://api.kapso.ai/mcp`  | Operating WhatsApp numbers with browser sign-in or an API key |
| Docs MCP    | `https://docs.kapso.ai/mcp` | Documentation lookup only                                     |

Use the [CLI](/docs/whatsapp/cli) when your agent has terminal access. Use Project MCP when your agent supports MCP and should operate Kapso directly.