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

# MCP Server

> Integrate Zavu API directly into AI assistants using Model Context Protocol

The Zavu MCP Server enables AI assistants like Claude, Cursor, and others to interact directly with the Zavu API. Send messages, manage templates, create broadcasts, and more through natural language.

## Quick Start

Run the MCP Server directly via npx:

```bash theme={null}
export ZAVUDEV_API_KEY="Your API Key"
npx -y @zavudev/sdk-mcp@latest
```

## Installation by Client

### Claude Desktop

Add to your Claude Desktop configuration file:

<CodeGroup>
  ```json macOS theme={null}
  // ~/Library/Application Support/Claude/claude_desktop_config.json
  {
    "mcpServers": {
      "zavudev_sdk_api": {
        "command": "npx",
        "args": ["-y", "@zavudev/sdk-mcp", "--client=claude", "--tools=dynamic"],
        "env": {
          "ZAVUDEV_API_KEY": "Your API Key"
        }
      }
    }
  }
  ```

  ```json Windows theme={null}
  // %APPDATA%\Claude\claude_desktop_config.json
  {
    "mcpServers": {
      "zavudev_sdk_api": {
        "command": "npx",
        "args": ["-y", "@zavudev/sdk-mcp", "--client=claude", "--tools=dynamic"],
        "env": {
          "ZAVUDEV_API_KEY": "Your API Key"
        }
      }
    }
  }
  ```
</CodeGroup>

### Cursor

Click the button below to install the MCP server in Cursor. You'll need to set your API key in Cursor's `mcp.json` (Settings > Tools & MCP > New MCP Server).

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@zavudev/sdk-mcp\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6YXZ1ZGV2L3Nkay1tY3AiXSwiZW52Ijp7IlpBVlVERVZfQVBJX0tFWSI6IlNldCB5b3VyIFpBVlVERVZfQVBJX0tFWSBoZXJlLiJ9fQ)

Or add manually:

```json theme={null}
{
  "mcpServers": {
    "zavudev_sdk_api": {
      "command": "npx",
      "args": ["-y", "@zavudev/sdk-mcp", "--client=cursor", "--tools=dynamic"],
      "env": {
        "ZAVUDEV_API_KEY": "Your API Key"
      }
    }
  }
}
```

### VS Code

Click the link below to install. Set your API key via Command Palette > MCP: Open User Configuration.

[Install in VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40zavudev%2Fsdk-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zavudev%2Fsdk-mcp%22%5D%2C%22env%22%3A%7B%22ZAVUDEV_API_KEY%22%3A%22Set%20your%20ZAVUDEV_API_KEY%20here.%22%7D%7D)

### Claude Code

Run in your terminal:

```bash theme={null}
claude mcp add --transport stdio zavudev_sdk_api --env ZAVUDEV_API_KEY="Your API Key" -- npx -y @zavudev/sdk-mcp
```

## Tool Exposure Modes

There are three ways to expose API endpoints as tools:

### Static Tools (Default)

Exposes one tool per API endpoint. Best for focused use cases where you know which endpoints you need.

### Dynamic Tools

Use `--tools=dynamic` to expose tools that discover and invoke endpoints on-demand:

| Tool                      | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `list_api_endpoints`      | Discovers available endpoints with optional filtering |
| `get_api_endpoint_schema` | Gets detailed schema for a specific endpoint          |
| `invoke_api_endpoint`     | Executes any endpoint with parameters                 |

This keeps context lightweight while providing full API access.

### Code Execution

Use `--tools=code` to expose:

| Tool          | Description                             |
| ------------- | --------------------------------------- |
| `search_docs` | Searches API documentation              |
| `execute`     | Runs code against the TypeScript client |

This allows the AI to implement complex logic by chaining API calls.

## Filtering Endpoints

Filter which tools are exposed:

```bash theme={null}
# Filter by resource
--resource=messages --resource=templates

# Filter by operation type
--operation=read   # Only get/list operations
--operation=write  # Only create/update/delete operations

# Include specific tools
--tool=send_messages --tool=list_templates

# Exclude specific tools
--no-tool=delete_senders

# Combine filters
--resource=messages --operation=read --no-tool=list_messages
```

Use `--list` to see all available tools.

## Client Configuration

Specify your MCP client for optimized compatibility:

```bash theme={null}
--client=claude
--client=claude-code
--client=cursor
--client=openai-agents
```

For advanced configuration, use capabilities:

```bash theme={null}
--capability=top-level-unions
--capability=tool-name-length=40
--capability=refs
--capability=unions
```

## Running Remotely

Launch as a remote HTTP server:

```bash theme={null}
npx -y @zavudev/sdk-mcp --transport=http --port=3000
```

Configure clients to connect:

```json theme={null}
{
  "mcpServers": {
    "zavudev_sdk_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

Query parameters work for filtering: `http://localhost:3000?resource=messages&operation=read`

## Available Tools

### Messages

| Tool                | Type  | Description                             |
| ------------------- | ----- | --------------------------------------- |
| `send_messages`     | write | Send SMS, WhatsApp, or email messages   |
| `retrieve_messages` | read  | Get message by ID                       |
| `list_messages`     | read  | List sent messages                      |
| `react_messages`    | write | Send emoji reaction to WhatsApp message |

### Templates

| Tool                 | Type  | Description                       |
| -------------------- | ----- | --------------------------------- |
| `create_templates`   | write | Create WhatsApp message template  |
| `retrieve_templates` | read  | Get template details              |
| `list_templates`     | read  | List all templates                |
| `delete_templates`   | write | Delete a template                 |
| `submit_templates`   | write | Submit template for Meta approval |

### Senders

| Tool                                | Type  | Description                      |
| ----------------------------------- | ----- | -------------------------------- |
| `create_senders`                    | write | Create sender profile            |
| `retrieve_senders`                  | read  | Get sender details               |
| `update_senders`                    | write | Update sender                    |
| `list_senders`                      | read  | List all senders                 |
| `delete_senders`                    | write | Delete sender                    |
| `get_profile_senders`               | read  | Get WhatsApp Business profile    |
| `update_profile_senders`            | write | Update WhatsApp Business profile |
| `upload_profile_picture_senders`    | write | Upload profile picture           |
| `regenerate_webhook_secret_senders` | write | Regenerate webhook secret        |

### Contacts

| Tool                         | Type  | Description                 |
| ---------------------------- | ----- | --------------------------- |
| `retrieve_contacts`          | read  | Get contact by ID           |
| `update_contacts`            | write | Update contact              |
| `list_contacts`              | read  | List all contacts           |
| `retrieve_by_phone_contacts` | read  | Get contact by phone number |

### Broadcasts

| Tool                         | Type  | Description                   |
| ---------------------------- | ----- | ----------------------------- |
| `create_broadcasts`          | write | Create broadcast campaign     |
| `retrieve_broadcasts`        | read  | Get broadcast details         |
| `update_broadcasts`          | write | Update draft broadcast        |
| `list_broadcasts`            | read  | List all broadcasts           |
| `delete_broadcasts`          | write | Delete draft broadcast        |
| `send_broadcasts`            | write | Start sending broadcast       |
| `cancel_broadcasts`          | write | Cancel active broadcast       |
| `progress_broadcasts`        | read  | Get real-time progress        |
| `add_broadcasts_contacts`    | write | Add contacts to broadcast     |
| `list_broadcasts_contacts`   | read  | List broadcast contacts       |
| `remove_broadcasts_contacts` | write | Remove contact from broadcast |

### Phone Numbers

| Tool                             | Type  | Description                |
| -------------------------------- | ----- | -------------------------- |
| `search_available_phone_numbers` | read  | Search numbers to purchase |
| `purchase_phone_numbers`         | write | Purchase a phone number    |
| `retrieve_phone_numbers`         | read  | Get phone number details   |
| `update_phone_numbers`           | write | Update phone number        |
| `list_phone_numbers`             | read  | List owned numbers         |
| `release_phone_numbers`          | write | Release a phone number     |

### Introspect

| Tool                        | Type  | Description                              |
| --------------------------- | ----- | ---------------------------------------- |
| `validate_phone_introspect` | write | Validate phone and check WhatsApp window |

## Usage Examples

Once configured, ask your AI assistant:

* "Send an SMS to +1234567890 saying 'Hello from Zavu'"
* "List my WhatsApp templates"
* "Create a broadcast campaign for Black Friday"
* "Check the progress of my current broadcast"
* "Search for available US phone numbers"

## Learn More

<CardGroup cols={2}>
  <Card title="Coding Agent Skills" icon="wand-magic-sparkles" href="/tools/coding-agent-skills">
    Add intelligent API context to your coding agent with pre-built skills
  </Card>

  <Card title="Model Context Protocol" icon="robot" href="https://modelcontextprotocol.io/">
    Learn about the MCP standard
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the full Zavu API
  </Card>
</CardGroup>