# @trillet-ai/mcp

> Official Trillet AI MCP server: build and manage voice agents, call flows, in-call API tools, knowledge bases, workflows, and call history from Claude.

Latest version **0.7.3** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @trillet-ai/mcp
pnpm add @trillet-ai/mcp
yarn add @trillet-ai/mcp
bun add @trillet-ai/mcp
```

Provides the command `trillet-mcp`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.7.3 |
| Published | 2026-09-24 |
| First published | 2026-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 189.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | trilletprod |
| Keywords | trillet, mcp, model-context-protocol, voice, phone, voice-agents |

## Links

- npm: https://www.npmjs.com/package/@trillet-ai/mcp
- Repository: https://github.com/TrilletAI/trillet-claude
- Homepage: https://trillet.ai
- Issues: https://github.com/TrilletAI/trillet-claude/issues
- npm.io page: https://npm.io/package/@trillet-ai/mcp

## Dependencies (3)

- [zod](https://npm.io/package/zod.md) ^3.24.0
- [zod-to-json-schema](https://npm.io/package/zod-to-json-schema.md) ^3.24.0
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.12.0

## Recent versions

- 0.7.3 (latest) — 2026-09-24

## README

# Trillet MCP Server

The official [Model Context Protocol](https://modelcontextprotocol.io) server for [Trillet AI](https://trillet.ai). Build and operate production voice agents from Claude: create agents, write call flows, wire in-call API tools, attach knowledge bases, configure post-call analysis, automate follow-ups with workflows, and debug real calls from their transcripts.

Built with the official TypeScript MCP SDK, stdio transport. 71 tools, all annotated with read-only/destructive hints.

## Setup

```bash
cd Trillet-MCP
npm install
npm run build
```

You need two values from the Trillet dashboard:

| Variable | Where to find it |
|---|---|
| `TRILLET_API_KEY` | Settings > API Keys |
| `TRILLET_WORKSPACE_ID` | Workspace settings (24-char hex id) |

Optional: `TRILLET_API_URL` (defaults to `https://api.trillet.ai`).

### npx (after npm publish)

The package is not on npm until someone with the `trillet-ai` org runs the steps in [PUBLISH.md](./PUBLISH.md). After that:

```bash
TRILLET_API_KEY=<your key> TRILLET_WORKSPACE_ID=<your workspace id> npx -y @trillet-ai/mcp
```

Cursor and Grok Bot install it from the public plugin repo [TrilletAI/Trillet-grok](https://github.com/TrilletAI/Trillet-grok) (`npx -y @trillet-ai/mcp@latest`, credentials from Plugins → Configure, not from the repo). The same tree is in `cursor-plugin/` here.

### Claude Code

```bash
claude mcp add trillet \
  -e TRILLET_API_KEY=<your key> \
  -e TRILLET_WORKSPACE_ID=<your workspace id> \
  -- node /absolute/path/to/Trillet-MCP/dist/index.js
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "trillet": {
      "command": "node",
      "args": ["/absolute/path/to/Trillet-MCP/dist/index.js"],
      "env": {
        "TRILLET_API_KEY": "<your key>",
        "TRILLET_WORKSPACE_ID": "<your workspace id>"
      }
    }
  }
}
```

Agency accounts: every tool accepts an optional `workspace_id` argument that overrides the default workspace for that call, so one server instance can manage client workspaces (the key's user must be a member of each).

## Tools

**Agents & voices** — `trillet_list_agents`, `trillet_get_agent`, `trillet_create_agent`, `trillet_update_agent`, `trillet_delete_agent` (requires `confirm: true`), `trillet_search_voices` (full multi-provider catalog)

**Call flows** — `trillet_list_call_flows`, `trillet_get_call_flow`, `trillet_create_call_flow`, `trillet_update_call_flow`, `trillet_update_prompt`, `trillet_set_incall_api_tools`, `trillet_set_post_call_analysis`, `trillet_list_drafts`, `trillet_deactivate_drafts`, `trillet_publish_draft`, `trillet_duplicate_call_flow`, `trillet_archive_call_flow`, `trillet_delete_call_flow` (requires `confirm: true`)

**Flow settings** — `trillet_set_transfers` (warm/cold/whisper/agent, condition gates, business-hours routing), `trillet_set_office_hours`, `trillet_set_call_settings` (voicemail detection, IVR navigation, silence, duration, recording), `trillet_set_speech_settings`, `trillet_set_welcome_message`, `trillet_set_code_actions` (feature-gated Python actions; detects silent strips)

**Node flows** — `trillet_node_flow_reference` (the full node-type/edge/validation reference the model reads before building), `trillet_list_node_flows`, `trillet_get_node_flow`, `trillet_create_node_flow`, `trillet_list_node_flow_templates`, `trillet_update_node_graph`, `trillet_validate_node_graph`, `trillet_publish_node_graph`, `trillet_simulate_node_graph`, `trillet_list_node_flow_runs`

**Phone numbers** — `trillet_list_phone_numbers`, `trillet_search_available_numbers`, `trillet_purchase_phone_number` (requires `confirm: true`; bills the workspace), `trillet_bind_phone_number` (office hours, metadata tags, secret bindings), `trillet_release_phone_number` (unbind from agent), `trillet_get_phone_number_config`, `trillet_update_phone_number_config`, `trillet_register_external_number` (BYO Twilio / SIP trunks, requires `confirm: true`)

**Knowledge bases** — `trillet_list_knowledge_bases`, `trillet_get_knowledge_base` (with flow usage), `trillet_create_knowledge_base`, `trillet_add_kb_text`, `trillet_upload_kb_file`, `trillet_attach_knowledge_bases`, `trillet_delete_knowledge_base` (whole KB or one file; requires `confirm: true`)

**Workflows** — `trillet_workflow_reference` (the full trigger/step/template reference the model reads before building: 7 triggers, 15 step types), `trillet_list_workflows`, `trillet_get_workflow`, `trillet_create_workflow`, `trillet_update_workflow`, `trillet_activate_workflow`, `trillet_pause_workflow`, `trillet_delete_workflow` (requires `confirm: true`), `trillet_test_workflow` (simulated side effects, works on drafts), `trillet_run_workflow` (real run, requires `confirm: true`), `trillet_list_workflow_runs`, `trillet_get_workflow_run` (per-step logs)

**Secrets** — `trillet_list_secrets` (always masked), `trillet_set_secret`, `trillet_delete_secret`

**Calls** — `trillet_list_calls` (filters + per-call cost/warm-transfer billing fields), `trillet_get_call_metrics` (aggregates), `trillet_get_call` (transcript, analysis, billing breakdown, optional functionCalls), `trillet_start_outbound_call` (requires explicit `confirm: true`; places a real phone call)

**Account** — `trillet_get_usage` (wallet balance, optional 3-month minutes breakdown), `trillet_list_transactions` (charge ledger, month x type summaries)

## Design notes

The tool descriptions encode hard-won platform behavior so the model does the right thing first time:

- **Editor drafts override production** for dashboard test calls; `trillet_get_call_flow` reports `has_active_draft` and `trillet_deactivate_drafts` returns a flow to production. This is the most common cause of "my changes aren't taking effect".
- **Update merge semantics**: objects deep-merge, arrays replace wholesale, nulls are ignored. The dedicated setters (`trillet_set_incall_api_tools`, `trillet_set_post_call_analysis`, `trillet_attach_knowledge_bases`) always send complete arrays.
- **In-call API tools**: the runtime appends call metadata to requests unless `callSetting.disableMetadata` is set; strict APIs (e.g. Airtable) reject unknown keys, so the setter defaults it on. Prompts should reference tools as `{{realtime_api "name" "vars"}}`.
- **Workflows**: `maxRunsPerContact` defaults to 1/24h platform-side (silently skips repeat callers); the create tool defaults it to 500. Web test calls fire the *outbound* call-completed trigger.
- **Prompts**: never script a greeting line in the prompt; the platform welcome message already plays it, and a scripted opening makes the agent greet twice.

## Roadmap to the Anthropic directory

- [x] Official SDK, stdio transport, tool annotations (`readOnlyHint`/`destructiveHint`), narrow tool descriptions, no dynamic code execution, secrets via env only
- [ ] Public privacy policy page (required for directory review)
- [ ] Remote server (Streamable HTTP + OAuth) for the Claude.ai connector directory (submission requires a Team/Enterprise org)
- [x] `.mcpb` Desktop Extension bundle for one-click local install (`trillet.mcpb` in the plugin repo)
- [ ] npm publish as `@trillet-ai/mcp` for `npx` usage (commands in [PUBLISH.md](./PUBLISH.md); not published yet)

## Security

- The API key and workspace id are read from environment variables and never logged.
- All output goes to stdout as MCP protocol messages; diagnostics go to stderr.
- Tools with real-world side effects or destructive outcomes (`trillet_start_outbound_call`, `trillet_run_workflow`, `trillet_purchase_phone_number`, `trillet_register_external_number`, and every delete tool) are annotated destructive and refuse to run without `confirm: true`.

---
_Source: https://npm.io/package/@trillet-ai/mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._