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

# MCP Server

> Connect Claude, Cursor, Windsurf, and any MCP client to your Tuco workspace. Send iMessages, reply to leads, and read analytics via the authed API.

## What is the Tuco MCP Server?

The Model Context Protocol (MCP) server lets AI assistants drive your Tuco workspace using natural language. Every tool call hits the same authenticated REST API as the Tuco dashboard, so anything an MCP client does is auditable in the activity log and visible in [/analytics](https://app.tuco.ai/analytics).

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

## Installation

```bash theme={null}
npx tuco-mcp
```

Package: [`tuco-mcp` on npm](https://www.npmjs.com/package/tuco-mcp). Tools across messaging, the unified inbox, replies, campaigns, leads, lines, and analytics.

## Configuration

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "tuco": {
      "command": "npx",
      "args": ["tuco-mcp"],
      "env": {
        "TUCO_API_KEY": "tuco_your_api_key"
      }
    }
  }
}
```

Get your API key from **[Integrations → API Keys](https://app.tuco.ai/integrations)** in the dashboard.

### Environment variables

| Variable       | Required | Default               | Description                                                                        |
| -------------- | -------- | --------------------- | ---------------------------------------------------------------------------------- |
| `TUCO_API_KEY` | Yes      | —                     | Your workspace API key (`tuco_…`).                                                 |
| `TUCO_API_URL` | No       | `https://app.tuco.ai` | API base URL. Override only if Tuco support points you at a different environment. |

Equivalent CLI flags: `npx tuco-mcp --api-key tuco_your_api_key --api-url https://app.tuco.ai`. Your key is bound to one workspace **and** one environment, so `TUCO_API_URL` must match the environment the key was issued for.

## Core Tools

The tools you'll reach for first:

| Tool                   | What it does                                                                                                                                           | Underlying endpoint                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `send-imessage`        | Send a single iMessage. Supports scheduling, attachments, SMS fallback, send windows.                                                                  | `POST /api/messages`                 |
| `send-batch`           | Send up to 1000 messages in one call.                                                                                                                  | `POST /api/messages/batch`           |
| `get-replies`          | Paginated reply list. Filter by campaign, lead, phone, email, **sending line**, and a **UTC date window**.                                             | `GET /api/replies`                   |
| `send-reply`           | Reply back in a conversation.                                                                                                                          | `POST /api/unibox/send-reply`        |
| `suggest-reply`        | AI-suggested reply options for a conversation (uses KB if configured).                                                                                 | `POST /api/unibox/suggest-reply`     |
| `list-conversations`   | Filter the unified inbox by status, tag, owner, custom property.                                                                                       | `GET /api/unibox/conversations`      |
| `analytics`            | Reached, sent, SMS fallback, failed, replied, unique repliers, reply %, positive replies, positive %. Filterable by campaign, line, user, date window. | `GET /api/analytics`                 |
| `cancel-lead-messages` | Cancel pending/queued/scheduled messages for a lead (e.g. on opt-out).                                                                                 | `POST /api/messages/cancel-for-lead` |

See the full list with `npx tuco-mcp --help` or any MCP client's tool browser.

## Example Prompts

Reply triage and outreach loop:

* "Send an iMessage to +12125551234 saying 'Hey, wanted to follow up'"
* "Fetch all replies received on line `<lineId>` between June 1 and June 10."
* "Show reply rate and positive reply rate for campaign `<campaignId>` over the last 7 days."
* "List my last 50 unread conversations, then suggest a reply for the top one."
* "Reply 'Thanks, sending a calendar link now' to the conversation with +12125551234."

The `get-replies` and `analytics` filters compose, so you can ask things like *"What's the positive reply rate on line X for campaign Y last week, and show me each replier."*

## Reply Pagination & Filters

`get-replies` mirrors the API:

| Param                 | Type     | Notes                                            |
| --------------------- | -------- | ------------------------------------------------ |
| `campaignId`          | string   | Restrict to replies from leads in this campaign. |
| `leadId`              | string   | A single lead.                                   |
| `recipientPhone`      | string   | E.164 or any normalizable format.                |
| `recipientEmail`      | string   | Exact match.                                     |
| `lineId`              | string   | Restrict to replies received on this Tuco line.  |
| `dateFrom` / `dateTo` | ISO 8601 | Inclusive UTC window on the reply timestamp.     |
| `page` / `limit`      | integer  | Default `page=1`, `limit=50`, max `100`.         |

The response includes `total`, `page`, `limit`, `totalPages`, and each row carries `recentReplies` (last 10 inbound) plus `parentMessages` (recent outbound) so the AI has full thread context without a second call.

Full schema, error codes, and an **interactive playground** are at [API → Check Replies](/api-reference/endpoint/get-replies).

## Analytics from the MCP

The `analytics` tool returns the same metric block the dashboard /analytics page reads, so the AI's answer and the UI agree exactly. Definitions, formulas, and the interactive playground live at [API → Analytics](/api-reference/analytics).

## See Also

* [Replies & Inbox](/features/replies) — conceptual model of how replies get matched and surfaced.
* [API Reference](/api-reference/introduction) — every endpoint with try-it-now playgrounds.
* [API Keys](/api-reference/api-keys) — generating and scoping keys.