@mindstone/mcp-server-retell-ai

Voice agent phone calls, call management, agent configuration, LLM prompt management, 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.2.2 · npm
• Auth: API key (RETELL_API_KEY)
• Tools: 20 (calls, agents, llms, voices)
• 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 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.

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 (20)

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

Agents

• get_agent — Get full configuration of a voice agent
• list_agents — List all configured voice agents
• 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

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

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

Configuration

• configure_retell_api_key — Save your Retell AI API key

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.