> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Model Context Protocol (MCP)

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard for connecting Large Language Models (LLMs) to platforms like Pinnacle. Once connected, your AI assistant can send SMS, MMS, and RCS messages, manage contacts, audiences, brands, and campaigns, purchase phone numbers, configure webhooks, and more — all on your behalf.

## MCP Installation

### Step 1: Configure your AI tool

Get your API key from the [Pinnacle Dashboard](https://app.pinnacle.sh/dashboard/development/api-keys), enter it below, and copy the configuration for your client.

### Step 2: Verify the connection

1. **Restart your AI client** — some clients require a restart to detect new MCP servers.
2. **Test the connection** by asking:
   > *"What phone numbers do I have available? Use MCP tools."*
3. Your AI assistant should call the Pinnacle MCP tools and return results from your account.

> **Troubleshooting**
>
> If tools aren't detected after restarting, double-check your API key and
> ensure the server URL is correct.

## Available Tools

The Pinnacle MCP server exposes **95 tools** organized by feature group.

### Messaging

| Tool                       | Description                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `send_sms`                 | Send an SMS message with optional scheduling                                               |
| `send_mms`                 | Send an MMS message with text and/or media files                                           |
| `send_rcs`                 | Send a rich RCS message with cards, buttons, and quick replies                             |
| `get_message`              | Retrieve details of a previously sent message by ID                                        |
| `list_messages`            | List messages with filtering by direction, status, type, sender, recipient, and date range |
| `list_scheduled_messages`  | List scheduled messages with filtering by status and schedule type                         |
| `send_typing_indicator`    | Show a typing indicator from an RCS agent                                                  |
| `cancel_scheduled_message` | Cancel a previously scheduled message before it is sent                                    |
| `react_to_message`         | Add or remove an emoji reaction on a message                                               |
| `validate_sms`             | Validate an SMS message — returns segment count, encoding, and estimated cost              |
| `validate_mms`             | Validate an MMS message — returns segment count, unsupported files, and estimated cost     |
| `validate_rcs`             | Validate an RCS message — returns segment count, unsupported files, and estimated cost     |

### Conversations

| Tool                         | Description                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `list_conversations`         | List conversations with optional filtering by brand, campaign, sender, or receiver |
| `get_conversation`           | Get a specific conversation by ID or phone numbers                                 |
| `list_conversation_messages` | Get paginated messages within a conversation with filtering                        |
| `update_conversation`        | Update notes on a conversation                                                     |

### Contacts

| Tool             | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `list_contacts`  | List contacts with filtering by phone number, name, tags, and archived status |
| `get_contact`    | Look up a contact by ID or phone number                                       |
| `create_contact` | Create a new contact with phone number and optional metadata                  |
| `update_contact` | Update an existing contact's name, email, tags, or description                |

### Audiences

| Tool                       | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `list_audiences`           | List audiences with optional name filtering            |
| `get_audience`             | Get an audience by ID with optional contact pagination |
| `create_audience`          | Create a new audience with optional initial contacts   |
| `update_audience`          | Update an audience's name or description               |
| `delete_audience`          | Delete an audience (does not delete its contacts)      |
| `add_audience_contacts`    | Add contacts to an existing audience                   |
| `remove_audience_contacts` | Remove contacts from an audience                       |

### Bulk Messaging

| Tool          | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `blast_sms`   | Send an SMS to all contacts in an audience with optional scheduling         |
| `blast_mms`   | Send an MMS to all contacts in an audience with optional scheduling         |
| `blast_rcs`   | Send an RCS message to all contacts in an audience with optional scheduling |
| `list_blasts` | List blasts with filtering by audience, sender, and content                 |

### Forms

| Tool                    | Description                                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `create_form`           | Create a hosted form without sending it — returns the form object including its public `https://forms.pinnacle.sh/{id}` URL  |
| `send_form`             | Create (or reuse) a form and deliver its URL over SMS or RCS in one call. Omit `to` to mint a standalone submission URL      |
| `get_form`              | Retrieve a form by ID — schema, theme override, submission count, last submission timestamp, and archive state               |
| `update_form`           | Partial update of a form's fields, theme, expiration, or archive state                                                       |
| `list_forms`            | Paginated list of forms on your team, sorted by creation date (newest first). Includes archived forms                        |
| `list_form_submissions` | Paginated list of completed submissions for a form, newest first, with the submitted data, sender, recipient, and timestamps |

### Phone Numbers

| Tool                          | Description                                                                |
| ----------------------------- | -------------------------------------------------------------------------- |
| `list_phone_numbers`          | List owned phone numbers with pagination                                   |
| `search_phone_numbers`        | Search available phone numbers to purchase by type, area code, and country |
| `get_phone_number_details`    | Get carrier, location, and contact info for any number                     |
| `buy_phone_numbers`           | Purchase one or more phone numbers                                         |
| `attach_campaign_to_phones`   | Attach a messaging campaign (10DLC or toll-free) to phone numbers          |
| `detach_campaign_from_phones` | Detach a messaging campaign from phone numbers                             |

### RCS Agents

| Tool                       | Description                                                                |
| -------------------------- | -------------------------------------------------------------------------- |
| `list_agents`              | List RCS agents with optional filtering by agent type                      |
| `get_test_agent`           | Get details of an RCS agent by ID, including carrier launch status         |
| `create_test_agent`        | Create a new RCS test agent with branding and contact info                 |
| `update_test_agent`        | Update an existing RCS test agent's configuration                          |
| `list_whitelisted_numbers` | List whitelisted phone numbers with filtering by agent, number, and status |
| `get_whitelist_status`     | Check the whitelist status of a phone number for a specific agent          |
| `whitelist_test_agent`     | Whitelist a phone number for RCS testing with an agent                     |
| `get_rcs_capabilities`     | Check if phone numbers support RCS and which features                      |
| `generate_rcs_link`        | Generate a deep link that opens an RCS conversation with your agent        |

### Brands

| Tool             | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `list_brands`    | List brands with filtering by status, name, and archived state       |
| `autofill_brand` | Auto-fill brand registration details using AI from a name or website |
| `upsert_brand`   | Create or update a brand for messaging campaign registration         |
| `get_brand`      | Retrieve a brand's full details by ID                                |
| `submit_brand`   | Submit a brand for carrier review                                    |
| `validate_brand` | Validate brand information before submission                         |
| `vet_brand`      | Request external third-party vetting for a brand via Aegis           |

### Campaigns

#### 10DLC

| Tool                    | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `list_dlc_campaigns`    | List 10DLC campaigns with filtering by status, brand, and name |
| `autofill_dlc_campaign` | Auto-fill 10DLC campaign details using AI                      |
| `upsert_dlc_campaign`   | Create or update a 10DLC campaign                              |
| `get_dlc_campaign`      | Retrieve a 10DLC campaign's full details                       |
| `submit_dlc_campaign`   | Submit a 10DLC campaign for carrier review                     |
| `validate_dlc_campaign` | Validate a 10DLC campaign before submission                    |

#### Toll-Free

| Tool                          | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `list_toll_free_campaigns`    | List toll-free campaigns with filtering by status, brand, and name |
| `autofill_toll_free_campaign` | Auto-fill toll-free campaign details using AI                      |
| `upsert_toll_free_campaign`   | Create or update a toll-free campaign                              |
| `get_toll_free_campaign`      | Retrieve a toll-free campaign's full details                       |
| `submit_toll_free_campaign`   | Submit a toll-free campaign for carrier review                     |
| `validate_toll_free_campaign` | Validate a toll-free campaign before submission                    |

#### RCS

| Tool                    | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `list_rcs_campaigns`    | List RCS campaigns with filtering by status, brand, and name |
| `autofill_rcs_campaign` | Auto-fill RCS campaign details using AI                      |
| `upsert_rcs_campaign`   | Create or update an RCS campaign with agent configuration    |
| `get_rcs_campaign`      | Retrieve an RCS campaign's full details                      |
| `submit_rcs_campaign`   | Submit an RCS campaign for carrier review                    |
| `validate_rcs_campaign` | Validate an RCS campaign before submission                   |

### Status

| Tool                            | Description                                         |
| ------------------------------- | --------------------------------------------------- |
| `get_brand_status`              | Check brand registration status                     |
| `get_dlc_campaign_status`       | Check 10DLC campaign status                         |
| `get_toll_free_campaign_status` | Check toll-free campaign status                     |
| `get_rcs_campaign_status`       | Check RCS campaign status                           |
| `get_phone_number_status`       | Check if a phone number is active and ready to send |

### Utility

| Tool                   | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `list_shortened_urls`  | List shortened URLs with pagination                                                   |
| `create_shortened_url` | Create a tracked short URL (pncl.to)                                                  |
| `get_shortened_url`    | Get details and click analytics for a shortened URL                                   |
| `update_shortened_url` | Update the destination or expiration of a shortened URL                               |
| `upload_file`          | Generate presigned upload/download URLs for file storage                              |
| `refresh_file_urls`    | Refresh expired presigned file URLs                                                   |
| `get_contact_card`     | Retrieve a contact card (vCard) by ID                                                 |
| `upsert_contact_card`  | Create or update a contact card (vCard)                                               |
| `list_webhooks`        | List webhooks with filtering by status and endpoint                                   |
| `get_webhooks`         | Retrieve webhooks attached to phone numbers or URLs                                   |
| `attach_webhook`       | Attach a webhook to senders, with optional custom HTTP headers sent on every delivery |
| `detach_webhook`       | Detach a webhook from senders (phone numbers or RCS agents)                           |

### Documentation

| Tool                   | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `search_pinnacle_docs` | Search Pinnacle docs for guides, API references, and examples |

## Configuration Options

| Option           | Description                    | Example                       |
| ---------------- | ------------------------------ | ----------------------------- |
| Remote URL       | Hosted Streamable HTTP server  | `https://mcp.pinnacle.sh/mcp` |
| npm package      | Local stdio via npx            | `npx @pinnacle-rcs/mcp`       |
| API key (remote) | Passed as HTTP header          | `PINNACLE-API-KEY: pnclk_...` |
| API key (local)  | Passed as environment variable | `PINNACLE_API_KEY=pnclk_...`  |

## Example Prompts

Here are some things you can ask your AI assistant once connected:

* *"Send an SMS to +14155551234 from my number saying 'Meeting at 3pm'"*
* *"Check if +14155551234 supports RCS"*
* *"Show me my recent conversations"*
* *"Create a new audience called 'Beta Testers' with these numbers: +14155551234, +14155556789"*
* *"Blast an SMS to my VIP audience saying 'Flash sale today!'"*
* *"Register my brand 'Acme Corp' with website acme.com — auto-fill the details"*
* *"Create a 10DLC campaign for customer care notifications"*
* *"Search for toll-free numbers and buy one"*
* *"Generate an RCS deep link for my agent"*
* *"Search the Pinnacle docs for how to set up RCS"*
* *"What's the status of my brand registration?"*
* *"Create a hosted contact-request form with name, email, and a 'how did you hear about us?' select, and send the URL to +14155551234 over RCS"*
* *"List submissions for form form\_Oy2n7iUoi9CJwUU6"*

## Source Code

The MCP server is open source: [github.com/pinnacle-dev/pinnacle-mcp](https://github.com/pinnacle-dev/pinnacle-mcp)

## Instructions for AI Agents

This page documents the Pinnacle MCP server. Key details:

* **Remote URL**: `https://mcp.pinnacle.sh/mcp`
* **Local**: `npx @pinnacle-rcs/mcp` (requires `PINNACLE_API_KEY` env var)
* **Auth**: `PINNACLE-API-KEY` header (remote) or `PINNACLE_API_KEY` env var (local)
* **npm package**: `@pinnacle-rcs/mcp`
* **95 tools** available for messaging (SMS/MMS/RCS), message listing and filtering, message validation, message reactions, scheduled message management, contacts, conversations, audiences, bulk messaging, hosted forms (create, send over SMS/RCS, get, update, list, list submissions), phone number management (search, purchase, list, webhooks, campaigns), RCS agents (list, get, capabilities, whitelisting, links, test agent management), brands (list, create, validate, submit, vet), campaigns (10DLC, toll-free, RCS — each with list, create, autofill, validate, submit), status checks, URL shortening/analytics, file uploads, contact cards, webhooks, and documentation search
* **Transports**: Streamable HTTP (remote) and stdio (local)