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

# MCP

> Use Clerk Chat tools from any MCP-compatible client

## Overview

Clerk Chat provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets you send messages, manage contacts, and run campaigns from any MCP-compatible client.

The MCP server is hosted at:

```
https://mcp.clerk.chat/
```

## Prerequisites

* A Clerk Chat account with an active workspace
* An MCP-compatible client (e.g., [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Claude Desktop](https://claude.ai/download), or any other MCP client)

## Authentication

The Clerk Chat MCP server uses OAuth for authentication. The first time you invoke a tool, your client will open a browser window to authenticate with your Clerk Chat account. After signing in, you'll be redirected back and the session will be active.

## Claude Code Setup

Add the Clerk Chat MCP server to Claude Code:

```bash theme={null}
claude mcp add clerk-chat --transport http https://mcp.clerk.chat/
```

To verify the connection, run:

```
/mcp
```

You should see `Authentication successful. Connected to clerk.` in the output.

## Available Tools

Once connected, the following tools are available:

### send\_message

Send an SMS/MMS message from a Clerk Chat inbox.

| Parameter      | Type      | Required | Description                                                |
| -------------- | --------- | -------- | ---------------------------------------------------------- |
| `sender`       | string    | Yes      | The Clerk phone number to send from (e.g., `+15551234567`) |
| `recipients`   | string\[] | Yes      | List of recipient phone numbers                            |
| `body`         | string    | Yes      | The message text content                                   |
| `media_urls`   | string\[] | No       | Media URLs to attach (for MMS)                             |
| `sent_by_name` | string    | No       | Display name for the sender                                |

### get\_messages

Retrieve messages for the active team with optional filtering.

| Parameter   | Type      | Required | Description                                   |
| ----------- | --------- | -------- | --------------------------------------------- |
| `inbox_ids` | string\[] | No       | Filter by specific inbox IDs                  |
| `start`     | string    | No       | Start datetime in ISO format                  |
| `end`       | string    | No       | End datetime in ISO format                    |
| `limit`     | integer   | No       | Max messages to return (default: 50, max: 50) |
| `page`      | integer   | No       | Page number for pagination (default: 1)       |

### create\_contact

Create a new contact in your workspace.

| Parameter | Type    | Required | Description                         |
| --------- | ------- | -------- | ----------------------------------- |
| `name`    | string  | No       | Contact name                        |
| `email`   | string  | No       | Contact email                       |
| `phone`   | string  | No       | Contact phone number                |
| `public`  | boolean | No       | Visible to all team members         |
| `data`    | object  | No       | Additional metadata key-value pairs |

### update\_contact

Update an existing contact.

| Parameter    | Type    | Required | Description                  |
| ------------ | ------- | -------- | ---------------------------- |
| `contact_id` | string  | Yes      | The contact ID to update     |
| `name`       | string  | No       | New name                     |
| `email`      | string  | No       | New email                    |
| `phone`      | string  | No       | New phone number             |
| `public`     | boolean | No       | Visibility setting           |
| `data`       | object  | No       | Metadata (replaces existing) |

### delete\_contact

Delete a contact by ID.

| Parameter    | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `contact_id` | string | Yes      | The contact ID to delete |

### create\_contacts\_batch

Create multiple contacts at once.

| Parameter  | Type      | Required | Description                                                |
| ---------- | --------- | -------- | ---------------------------------------------------------- |
| `contacts` | object\[] | Yes      | Array of contact objects (same fields as `create_contact`) |

### create\_campaign

Send a message to all contacts in a list.

| Parameter    | Type      | Required | Description                                    |
| ------------ | --------- | -------- | ---------------------------------------------- |
| `sender`     | string    | Yes      | The Clerk phone number to send from            |
| `list_name`  | string    | Yes      | Name of the recipient list                     |
| `body`       | string    | Yes      | Message content                                |
| `media_urls` | string\[] | No       | Media URLs to attach                           |
| `name`       | string    | No       | Campaign name                                  |
| `timestamp`  | string    | No       | Scheduled send time (ISO format)               |
| `provider`   | string    | No       | SMS provider (twilio, bandwidth, telnyx, etc.) |

## Examples

**Send a message:**

> Send a message from +15551234567 to +15559876543 saying "Your appointment is confirmed for tomorrow at 2pm"

**Check recent messages:**

> Show me the last 10 messages from inbox 5d0e8d03-d09f-47e5-8017-4d00cbf737f4

**Create a contact:**

> Create a contact for Jane Smith with phone +15551234567 and email [jane@example.com](mailto:jane@example.com)

## Troubleshooting

| Issue                               | Solution                                                         |
| ----------------------------------- | ---------------------------------------------------------------- |
| `Session not found` error           | Run `/mcp` to reconnect                                          |
| `Authentication failed`             | Run `/mcp` to clear and re-authenticate                          |
| Tools not appearing                 | Run `/mcp` to reconnect, then retry                              |
| `Unauthorized` errors on tool calls | Your OAuth token may have expired. Run `/mcp` to re-authenticate |