@mindstone/mcp-server-retell-ai

Voice agent phone calls, batch calling campaigns, call management, agent configuration, LLM prompt management, knowledge bases, chat history, and voice discovery via Retell AI API.

Best for MCP hosts that want a local voice-operations connector for placing calls, checking call history, and adjusting agent prompts with user confirmation.

Status

• Version: 0.3.0 · npm
• Auth: API key (RETELL_API_KEY)
• Tools: 32 (calls, agents, llms, voices, knowledge bases, chats)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

Retell's hosted MCP server is the best fit for clients that support remote MCP over HTTP. This package is for local stdio hosts that want Retell voice operations through the same npm-based connector flow as the rest of this repo.

It turns voice-agent work into a clear assistant workflow: inspect the agent and prompt, choose the right phone number, place or create a web call, then monitor the result. The value is not just API access; it helps keep real-world call actions deliberate, reviewable, and tied to the right agent configuration.

Example interaction

"Call Jane to confirm tomorrow's appointment using our support agent."

Tools the host calls:

1. list_agents — finds the support agent and its agent ID.
2. get_retell_llm — checks the prompt and supported dynamic variables.
3. list_phone_numbers — finds a registered outbound number.
4. create_phone_call — places the call after host/user confirmation.
5. get_call — checks call status, transcript, and recording details.

Response (trimmed):

{
  "ok": true,
  "call_id": "call_01HXX...",
  "status": "registered",
  "from_number": "+14155551234",
  "to_number": "+14155559876",
  "warnings": []
}

Requirements

• Node.js 20+
• npm
• A Retell AI API key.

One-click install

After clicking the button, your host will prompt you to fill: RETELL_API_KEY.

{
  "mcpServers": {
    "Retell AI": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-retell-ai"
      ],
      "env": {
        "RETELL_API_KEY": ""
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/retell-ai
npm install
npm run build

npx

npx -y @mindstone/mcp-server-retell-ai

Local

node dist/index.js

Configuration

Set the following environment variable:

| Variable | Required | Description | |---|---|---| | RETELL_API_KEY | Yes | Retell AI API key. Get one at retellai.com/dashboard | | MCP_WORKSPACE_PATH | No | Workspace directory for local files uploaded as knowledge-base sources (create_knowledge_base / add_knowledge_base_sources file_paths). File reads are sandboxed to this directory; defaults to the system temp directory. |

MCP Host Configuration

{
  "mcpServers": {
    "retell-ai": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-retell-ai"],
      "env": {
        "RETELL_API_KEY": "your-api-key"
      }
    }
  }
}

Security notes

Outbound phone calls require host confirmation

create_phone_call is marked as a real-world action. The MCP host MUST require explicit user confirmation before invoking it. Outbound calls are billed per minute against your Retell AI plan and a misfired call has real-world consequences (a stranger's phone rings, a recording is captured, your account is charged) that cannot be undone.

Hosts integrating this connector are required to:

• Surface the proposed from_number and to_number to the user before each invocation.
• Block the call until the user explicitly confirms.
• Never auto-approve create_phone_call based on prior approvals — each call MUST be confirmed individually.

from_number and to_number are validated against the E.164 regex /^\+[1-9]\d{1,14}$/ before any upstream request is made. Numbers must:

• Start with +, followed by a country-code digit 1-9 (no leading zero).
• Contain only digits — spaces, dashes, parentheses are rejected.
• Be 2-15 digits long inclusive of the country code.

Malformed numbers are rejected locally with a structured INVALID_PHONE_NUMBER error and are never sent upstream.

Batch calls multiply the blast radius

create_batch_call places one real, billed phone call per task. The same confirmation rules as create_phone_call apply to the whole batch: the host MUST surface the full recipient list (from_number plus every to_number) and get explicit user confirmation before invoking it. Consider checking get_concurrency first so a campaign does not starve inbound capacity.

Knowledge-base file uploads are workspace-sandboxed

create_knowledge_base and add_knowledge_base_sources accept local file_paths. Reads are constrained to MCP_WORKSPACE_PATH (or the system temp directory when unset) using canonical-prefix containment: .. traversal, absolute paths outside the sandbox, and symlinks that escape it are rejected before any disk read. The read itself is open-then-validate: the connector opens a descriptor, confirms the opened inode is the file the sandbox approved, reads through that descriptor, and re-checks the descriptor after the read — a file swapped, replaced, or modified between validation and read fails closed, and the 50MB bound is enforced on the bytes actually read. Retell limits uploads to 25 files, 50MB each.

Dynamic-variable pre-call validation is observable and ordered

create_phone_call, create_web_call, and create_batch_call validate passed retell_llm_dynamic_variables against the live prompt BEFORE the call/session/campaign is created, keyed by the effective (agent_id, agent_version) so the prompt validated is the prompt that will run. The check never blocks an explicitly-requested call, but it also never fails silently: unmatched variables, an unidentifiable prompt (e.g. a conversation-flow agent), and lookup failures each surface as explicit warnings in the tool response.

Delete tools are permanent

delete_agent, delete_retell_llm, and delete_phone_number are irreversible: agent and LLM deletion removes ALL versions, and a deleted phone number is released (you may not get the same number back). Hosts should require explicit confirmation and encourage checking bindings first (list_phone_numbers, get_agent).

Configuration changes also need review

The connector also marks agent creation/updates, agent publishing, LLM prompt creation/updates, phone-number updates, web-call creation, active-call stopping, and API-key configuration as reviewable actions. Hosts should treat them carefully because they can alter live call behaviour, costs, or credentials.

Tools (32)

Phone Calls

• create_phone_call — Create an outbound phone call using a Retell AI voice agent
• create_web_call — Create a browser-based voice call with a Retell AI agent
• get_call — Get details about a specific call (status, transcript, recording)
• list_calls — List and filter calls by agent, time range, or status
• stop_call — Terminate an active call
• get_concurrency — Check account call-capacity headroom before a batch or burst

Batch Calls

• create_batch_call — Schedule or start an outbound calling campaign (one from_number, many recipients)

Agents

• get_agent — Get full configuration of a voice agent
• list_agents — List configured voice agents (paginated)
• create_agent — Create a new voice agent
• update_agent — Update an existing agent's configuration
• publish_agent — Publish an agent draft to make it callable
• get_agent_versions — List version history for an agent
• delete_agent — Permanently delete an agent and all its versions

LLM Configuration

• update_retell_llm — Update the LLM configuration (prompt, greeting, model)
• get_retell_llm — Get the full LLM configuration
• create_retell_llm — Create a new LLM configuration
• list_retell_llms — List all LLM configurations
• delete_retell_llm — Permanently delete an LLM configuration and all its versions

Knowledge Bases

• list_knowledge_bases — List knowledge bases and their processing status
• get_knowledge_base — Get a knowledge base's sources and status
• create_knowledge_base — Create a knowledge base from texts, URLs, and/or sandboxed local files
• add_knowledge_base_sources — Add texts, URLs, or files to an existing knowledge base

Chats

• list_chat_agents — List configured chat agents (paginated)
• list_chats — List and filter chat sessions by agent or time range
• get_chat — Get a chat's full transcript and analysis

Discovery

• list_voices — List available text-to-speech voices
• list_phone_numbers — List registered phone numbers
• get_phone_number — Get details of a specific phone number
• update_phone_number — Update a phone number's agent assignment
• delete_phone_number — Permanently release a phone number

Configuration

• configure_retell_api_key — Save your Retell AI API key

Vendor deprecation watch

Retell ships breaking endpoint changes on short notice — this connector has already migrated twice (the v2/v3 call-endpoint round in 0.2.0, and list_agents moving to the unified POST /v2/list-agents after the 2026-07-31 deprecation). Maintainers: re-check the Retell deprecation notices before each release and after any unexplained 404/410 from a previously working tool. Known upcoming: "Update Call restricted to ended calls" (2026-08-31) — this connector does not expose update-call, so no action is needed today.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.