MCP Server

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. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Installation

npx tuco-mcp

Package: tuco-mcp on npm. Tools across messaging, the unified inbox, replies, campaigns, leads, lines, and analytics.

Configuration

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

{
  "mcpServers": {
    "tuco": {
      "command": "npx",
      "args": ["tuco-mcp"],
      "env": {
        "TUCO_API_KEY": "tuco_your_api_key"
      }
    }
  }
}

Get your API key from Integrations → API Keys 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.

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.

Getting Started

Core Features

Campaigns & Messaging Engine

Architecture & Operations

AI & Automation

Messaging & Compliance

Operations

Analytics & Reporting

AI & Automation

Lead Management

Integrations

FAQ

What is the Tuco MCP Server?

Installation

Configuration

Environment variables

Core Tools

Example Prompts

Analytics from the MCP

See Also

​What is the Tuco MCP Server?

​Installation

​Configuration

​Environment variables

​Core Tools

​Example Prompts

​Reply Pagination & Filters

​Analytics from the MCP

​See Also

What is the Tuco MCP Server?

Installation

Configuration

Environment variables

Core Tools

Example Prompts

Reply Pagination & Filters

Analytics from the MCP

See Also