# Retell AI (npm · @mindstone/mcp-server-retell-ai)

Retell AI MCP server: voice agent phone calls, agent management, LLMs, and voice discovery

- Trust score: 72/100 (medium)
- Change this week: +48
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-04

## Components

- npm · `@mindstone/mcp-server-retell-ai`: 72/100 (this document), [markdown](https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai.md), [page](https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai)

## Channel facts

- Registry: `npm`
- Package: `@mindstone/mcp-server-retell-ai`
- Version: `0.2.4`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-04.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 84/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to mindstone/mcp-servers).
  - License check failed: the license (FSL-1.1-MIT) isn't a recognized OSI-approved license.
  - Actively maintained (last published 53 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 51/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 7279 tokens (~363/item across 20 items; 20 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add mindstone-mcp-server-retell-ai -- npx -y @mindstone/mcp-server-retell-ai
```

### Codex

```bash
codex mcp add mindstone-mcp-server-retell-ai -- npx -y @mindstone/mcp-server-retell-ai
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mindstone-mcp-server-retell-ai": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mindstone/mcp-server-retell-ai"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add mindstone-mcp-server-retell-ai --command npx --arg -y --arg @mindstone/mcp-server-retell-ai
```

### Hermes

```yaml
mcp_servers:
  mindstone-mcp-server-retell-ai:
    command: "npx"
    args: ["-y", "@mindstone/mcp-server-retell-ai"]
```

### Other

```json
{
  "mcpServers": {
    "mindstone-mcp-server-retell-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-retell-ai"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 72, +4)

- [functional improvement] Stability: unverified → 0.23

### 2026-08-02 (score 68, +63)

- [security improvement] Provenance: unverified → pass
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [security] The attested source repository moved: mindstone/mcp-servers
- [functional regression] License: unverified → fail
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: FSL-1.1-MIT

### 2026-08-01 (score 5, −17)

- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-31 (score 22, −2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-28 (score 24, −17)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 41)

First indexed and scored.

## MCP tools (20)

### `create_phone_call` (~787 tokens)

Create an outbound phone call using a Retell AI voice agent.

WHEN TO USE: User asks you to make, place, or initiate a phone call.

WORKFLOW (typical sequence):
1\. list_agents → find the right agent, note its agent_id
2\. get_agent → check config, get its retell_llm_id
3\. update_retell_llm → set the conversation prompt/instructions
4\. Wait 2-3 seconds (let config propagate)
5\. create_phone_call → initiate the call
6\. Poll get_call every 5-10s until status is "ended"

EXAMPLE:
{ "from_number": "+14155551234", "to_number": "+14155559876", "override_agent_id": "agent_xxx", "override_agent_version": 2 }

COMMON MISTAKES:
\- Skipping update_retell_llm first: the agent will use the previous call's prompt
\- Passing override_agent_id without override_agent_version: Retell may route to the wrong or unpublished version
\- Assuming the phone number is already bound: check list_phone_numbers/get_phone_number
\- Updating the agent or LLM but not publishing the version before calling

ERROR RECOVERY:
\- 401: API key is missing or invalid → ask the user for the key, then configure_retell_api_key
\- 404: resource/version/binding not found → check phone number outbound_agents, get_agent_versions, then publish_agent or pass override_agent_version
\- 422: bad parameter shape/value → verify E.164 phone numbers and valid agent/version IDs

CRITICAL: If the call returns 404, the most common causes are:
\- The phone number has no outbound agent bound → use update_phone_number to bind one
\- The agent version is unpublished → use publish_agent first, or pass override_agent_version
\- Always pass override_agent_id AND override_agent_version for reliable routing

RELATED TOOLS:
\- update_retell_llm: Set the prompt before placing the call
\- get_phone_number/list_phone_numbers: Verify outbound bindings and from_number
\- publish_agent/get_agent_versions: Confirm the version is live
\- get_call: Monitor status and retrieve transcript/recording

RETURNS: call_id, status, agent_id, from_number, to_number, st…

Input parameters:

- `from_number` (string, required): Caller phone number in E.164 format (e.g. +14155551234). Must be registered in Retell and have an outbound agent binding. Use list_phone_numbers to find available numbers.
- `metadata` (object): Custom metadata key-value pairs to attach to this call (for CRM IDs, campaign IDs, user context).
- `override_agent_id` (string): Agent ID to use for this call. If set, also pass override_agent_version for reliable routing. If omitted, uses the default agent assigned to from_number.
- `override_agent_version`: Agent version: number (0, 1, 2...) or tag ("latest", "prod"). Use with override_agent_id for reliable routing to a published version.
- `retell_llm_dynamic_variables` (object): Dynamic variables to inject into the prompt template (e.g. { customer_name: 'Jane', account_tier: 'pro' }). WARNING: These ONLY work if the LLM prompt already contains matching {{variable_name}} plac…
- `to_number` (string, required): Recipient phone number in E.164 format (e.g. +14155559876).

### `create_web_call` (~425 tokens)

Create a browser-based voice call session. Returns a web_call_link the user can open to talk to a Retell agent.

WHEN TO USE:
\- User wants a voice call in their browser instead of their phone
\- Phone call route is blocked (e.g. phone number binding issue)
\- Testing or demoing an agent without using phone minutes

EXAMPLE:
{ "agent_id": "agent_xxx", "agent_version": "latest", "retell_llm_dynamic_variables": { "customer_name": "Jane" } }

COMMON MISTAKES:
\- Forgetting agent_version when testing a specific published version
\- Sharing an old web_call_link instead of creating a fresh session

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: agent/version not found → list_agents, get_agent_versions, then publish_agent if needed
\- 422: bad dynamic variable shape → send a plain JSON object

RELATED TOOLS:
\- list_agents/get_agent: Find the agent_id and response engine
\- update_retell_llm: Set the prompt before creating the test session
\- get_call: Retrieve transcript, analysis, and recording after the session

RETURNS: call_id, web_call_link, status, agent_id, access_token. Share web_call_link with the user.

Input parameters:

- `agent_id` (string, required): Agent ID to handle the web call. Use list_agents/get_agent to verify it first.
- `agent_version`: Agent version to use: number (0, 1, 2...) or tag (e.g. "latest", "prod"). Pass this when validating a specific published version.
- `metadata` (object): Custom metadata for this call (CRM IDs, test labels, scenario names).
- `retell_llm_dynamic_variables` (object): Dynamic prompt variables used by the Retell LLM prompt template. WARNING: Only works if the LLM prompt contains matching {{variable_name}} placeholders. Unmatched variables are silently dropped. Chec…

### `get_call` (~244 tokens)

Get details of a specific call including status, transcript, recording URL, and duration.

WHEN TO USE:
\- After create_phone_call or create_web_call to monitor progress
\- To retrieve the full transcript after a call ends
\- To check call status: "registered" (queued), "ongoing" (live), "ended" (complete), "error" (failed)

WORKFLOW: Poll every 5-10 seconds after creating a call until status is "ended" or "error".

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: call_id not found → check the ID returned by create_phone_call/create_web_call or use list_calls

RELATED TOOLS:
\- create_phone_call/create_web_call: Source of call_id
\- list_calls: Find recent call IDs if call_id is unknown
\- stop_call: End an ongoing call

RETURNS: call_id, status, transcript, transcript_object, recording_url, call_analysis, duration_ms, disconnection_reason.

Input parameters:

- `call_id` (string, required): The call ID returned by create_phone_call/create_web_call or found via list_calls.

### `list_calls` (~392 tokens)

List calls with filtering and pagination. Returns recent calls by default (newest first).

WHEN TO USE:
\- Browse call history
\- Find calls by agent, date range, or status
\- Verify recent call activity

FILTERING:
\- agent_id accepts an array of one or more agent IDs
\- filter_criteria timestamps accept Unix milliseconds (number) or a parseable date string (e.g. "2026-01-01"); date strings are converted to milliseconds before the API call
\- Example: { "limit": 20, "agent_id": ["agent_xxx"], "filter_criteria": { "after_start_timestamp": 1735689600000 } }

COMMON MISTAKES:
\- Passing one agent_id as a string instead of an array
\- Using seconds for numeric timestamps; Retell expects milliseconds

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 422: invalid filter shape → check agent_id is an array and numeric timestamps are milliseconds

RELATED TOOLS:
\- get_call: Get transcript/recording/analysis for a returned call_id
\- list_agents: Find agent IDs for filtering
\- stop_call: End an ongoing call

RETURNS: calls, count, pagination_key, has_more. Each call includes call_id, status, agent_id, timestamps, and call metadata.

Input parameters:

- `agent_id` (array): Filter calls by one or more agent IDs. Must be an array, even for one agent: ["agent_xxx"].
- `filter_criteria` (object): Time-based filters for narrowing call results.
- `limit` (integer): Max results (1-1000). Default: 50.
- `pagination_key` (string): Pagination key from previous response for the next page.
- `sort_order` (string): Sort by start time. Default: descending (newest first).

### `stop_call` (~173 tokens)

Stop an ongoing call immediately.

WHEN TO USE:
\- User wants to end a call in progress
\- Call is stuck or behaving unexpectedly
\- Emergency stop

COMMON MISTAKES:
\- Calling this on an already ended call; use get_call first if unsure

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: call_id not found or no longer active → verify with list_calls/get_call

RELATED TOOLS:
\- get_call: Check whether status is "ongoing" before stopping
\- list_calls: Find the active call_id

RETURNS: ok, message. Retell returns HTTP 204 on success.

Input parameters:

- `call_id` (string, required): The call ID of the ongoing call to stop. Confirm status with get_call when possible.

### `get_agent` (~277 tokens)

Get full configuration of a voice agent including voice, LLM, language, and versioning info.

WHEN TO USE:
\- Before making a call, to check the agent's retell_llm_id (needed for update_retell_llm)
\- To verify which voice, language, or phone number an agent uses
\- To check the agent's current version and published state

COMMON MISTAKES:
\- Updating the wrong LLM: use response_engine.llm_id from this tool before update_retell_llm
\- Assuming draft changes are live: use get_agent_versions/publish_agent to confirm

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: agent_id not found → list_agents and retry with the returned ID

RELATED TOOLS:
\- list_agents: Discover agent IDs
\- get_agent_versions: Inspect draft/published versions
\- update_retell_llm: Update the linked response_engine.llm_id
\- create_phone_call: Use this agent after validating config

RETURNS: agent_id, agent_name, voice_id, response_engine.llm_id, language, version, published/versioning fields, phone number bindings when available.

Input parameters:

- `agent_id` (string, required): The agent ID to look up. Use list_agents if you only know the name.

### `list_agents` (~168 tokens)

List all configured voice agents in your Retell account.

WHEN TO USE:
\- Discover available agents before making calls
\- Find agent IDs by name
\- Inventory check

COMMON MISTAKES:
\- Guessing agent IDs from names; use the returned agent_id exactly
\- Choosing an agent without checking its response_engine.llm_id and versions via get_agent

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key

RELATED TOOLS:
\- get_agent: Inspect full config for a returned agent_id
\- get_agent_versions: Check published versions
\- create_phone_call/create_web_call: Use a verified agent_id

RETURNS: agents, count. Each agent usually includes agent_id, agent_name, voice_id, response_engine, and timestamps.

### `create_agent` (~439 tokens)

Create a new voice agent with specified voice, LLM, and language settings.

WHEN TO USE:
\- Setting up a new voice agent from scratch
\- No existing agent fits the use case

WORKFLOW:
1\. list_voices → choose voice_id
2\. create_retell_llm → create prompt/model config
3\. create_agent → point response_engine.llm_id at that LLM
4\. publish_agent → make the version live
5\. update_phone_number → bind the agent for calls

EXAMPLE:
{ "agent_name": "Sales qualifier", "voice_id": "11labs-Adrian", "response_engine": { "type": "retell-llm", "llm_id": "llm_xxx" }, "language": "en-US" }

COMMON MISTAKES:
\- Creating the agent before creating/selecting a Retell LLM
\- Forgetting to publish and bind the agent to a phone number before create_phone_call

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: voice_id or llm_id not found → list_voices/list_retell_llms and retry
\- 422: invalid config → verify response_engine is { "type": "retell-llm", "llm_id": "..." }

RELATED TOOLS:
\- list_voices: Choose a voice_id
\- create_retell_llm/list_retell_llms: Choose or create the LLM
\- publish_agent: Make the new version live
\- update_phone_number: Bind for inbound/outbound calls

RETURNS: agent_id, agent_name, voice_id, response_engine, language, version fields.

Input parameters:

- `agent_name` (string): Display name for the agent (e.g. "Sales qualifier").
- `language` (string): Language code (e.g. "en-US", "es-ES"). Default: en-US.
- `response_engine` (object): Response engine configuration linking the agent to an LLM.
- `voice_id` (string): Voice to use. Get valid IDs from list_voices.

### `update_agent` (~465 tokens)

Update an existing agent's configuration (voice, name, response engine, language, etc.).

WHEN TO USE:
\- Change voice, language, response engine, responsiveness, or backchannel behavior
\- Point an agent at a different Retell LLM

NOTE: This updates the agent's latest DRAFT version. To make changes live, call publish_agent afterward.

COMMON MISTAKES:
\- Updating the agent and immediately calling without publish_agent
\- Switching response_engine.llm_id without checking the LLM config first

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: agent_id/voice_id/llm_id not found → use list_agents/list_voices/list_retell_llms
\- 422: invalid setting range → check numeric ranges on speed/responsiveness/sensitivity

RELATED TOOLS:
\- get_agent: Inspect current config before changing
\- publish_agent/get_agent_versions: Publish and verify draft changes
\- update_retell_llm: Change prompt/model without replacing the response engine

RETURNS: Updated agent object including agent_id, agent_name, voice_id, response_engine, language, draft/version fields.

Input parameters:

- `agent_id` (string, required): Agent ID to update. Use get_agent first when unsure.
- `agent_name` (string): New display name.
- `ambient_sound` (string): Background ambience sound.
- `boosted_keywords` (array): Words to boost in speech recognition (names, brands, etc.).
- `enable_backchannel` (boolean): Whether the agent says "yeah", "uh-huh" during user speech.
- `interruption_sensitivity` (number): How easily user can interrupt (0=never, 1=easy). Default: 1.
- `language` (string): New language code (e.g. "en-US", "es-ES").
- `response_engine` (object): Updated response engine config.
- `responsiveness` (number): How quickly the agent responds (0=slow, 1=fast). Default: 1.
- `voice_id` (string): New voice ID. Get IDs from list_voices.
- `voice_speed` (number): Speech rate (0.5=slow, 2=fast). Default: 1.

### `publish_agent` (~346 tokens)

Publish a specific agent version, making it the active/live version.

WHEN TO USE:
\- After updating an agent's config or LLM, to make changes live
\- When create_phone_call returns 404 because the agent version is unpublished
\- When you need to activate a specific version

CRITICAL: Agent updates go to the latest DRAFT version. They are NOT live until published.
If calls fail with 404, check get_agent_versions and publish the correct version.

WORKFLOW:
1\. update_agent or update_retell_llm → changes the draft
2\. get_agent_versions → find the version number of the draft
3\. publish_agent → make it live

COMMON MISTAKES:
\- Publishing the wrong version number; call get_agent_versions immediately before this
\- Assuming update_retell_llm alone publishes changes

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: agent/version not found → list_agents/get_agent_versions
\- 422: version is invalid or not publishable → verify the draft version number

RELATED TOOLS:
\- get_agent_versions: Find the version number to publish
\- update_agent/update_retell_llm: Make draft changes first
\- create_phone_call: Use the published version afterward

RETURNS: ok, message confirming the agent_id and published version.

Input parameters:

- `agent_id` (string, required): Agent ID to publish. Use list_agents/get_agent if needed.
- `version` (integer, required): Version number to publish. Get the exact number from get_agent_versions.
- `version_description` (string): Optional description of this version (e.g. what prompt/config changed).

### `get_agent_versions` (~214 tokens)

List all versions of an agent, including draft and published versions.

WHEN TO USE:
\- To check which version is currently published/live
\- To find the version number of a draft before publishing
\- To debug version mismatch issues causing 404 errors on calls

COMMON MISTAKES:
\- Using override_agent_id without checking the matching override_agent_version here
\- Publishing/calling a stale version after updating the draft

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: agent_id not found → list_agents and retry

RELATED TOOLS:
\- publish_agent: Publish a draft version returned here
\- create_phone_call: Pass override_agent_version from this list
\- get_agent: Inspect the agent tied to these versions

RETURNS: versions, count. Each version includes version number, published/live status, creation/update timestamps, and description when available.

Input parameters:

- `agent_id` (string, required): Agent ID to list versions for. Use list_agents if unknown.

### `update_retell_llm` (~775 tokens)

Update a Retell LLM response engine's prompt, model, or behavior settings.

WHEN TO USE:
\- Before making a call, to set the conversation instructions/prompt
\- To change the LLM model or temperature
\- To update the agent's opening message

CRITICAL: This is the #1 most important step before any phone call. The general_prompt controls what the agent says. If you skip this, the agent will use the PREVIOUS call's prompt.

WORKFLOW:
1\. get_agent → find the agent's retell_llm_id (in response_engine.llm_id)
2\. update_retell_llm → set the prompt and behavior
3\. get_agent_versions/publish_agent if the agent version needs publishing
4\. Wait 2-3 seconds for propagation
5\. create_phone_call

MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite.

EXAMPLE:
{ "llm_id": "llm_xxx", "general_prompt": "You are calling to confirm tomorrow's appointment. Be concise and polite.", "begin_message": "Hi, this is Alex calling to confirm your appointment.", "model": "gpt-5.5" }

COMMON MISTAKES:
\- Skipping this before create_phone_call, causing the previous call's prompt to run
\- Updating the wrong llm_id; get it from get_agent.response_engine.llm_id
\- Forgetting to publish the agent/version after changing call behavior

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: llm_id not found → get_agent or list_retell_llms
\- 422: invalid model/prompt/tools → use a listed model and valid JSON tool config

RELATED TOOLS:
\- get_agent: Find the linked response_engine.llm_id
\- get_retell_llm: Inspect current prompt/model before changing
\- publish_agent/get_agent_versions: Make agent changes live
\- create_phone_call/create_web_call: Test the updated behavior

RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, updated timestamps.

Input parameters:

- `begin_message` (string): First message the agent speaks when the call connects (e.g. "Hi, this is Sarah from Acme Corp.").
- `general_prompt` (string): System prompt/instructions for the voice agent. This controls what the agent says; update it before each call-specific scenario.
- `general_tools` (array): Tools available to the LLM during calls (advanced). Must match Retell tool schema.
- `llm_id` (string, required): The LLM config ID to update. Get from get_agent → response_engine.llm_id or list_retell_llms.
- `model` (string): LLM model. Options: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite.
- `model_temperature` (number): Temperature (0=deterministic, 2=creative). Default: varies by model.

### `get_retell_llm` (~246 tokens)

Get details of a Retell LLM response engine (prompt, model, tools).

WHEN TO USE:
\- Inspect current prompt/model before update_retell_llm
\- Confirm which prompt an agent will use before a call
\- Debug why an agent said the wrong thing

COMMON MISTAKES:
\- Looking at the agent only; the actual call instructions live in the Retell LLM
\- Editing a different LLM than the one returned by get_agent.response_engine.llm_id

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: llm_id not found → get_agent/list_retell_llms and retry

RELATED TOOLS:
\- get_agent: Find response_engine.llm_id for an agent
\- update_retell_llm: Change the prompt/model
\- list_retell_llms: Browse available LLM configs

RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.

Input parameters:

- `llm_id` (string, required): The Retell LLM config ID. Usually get this from get_agent → response_engine.llm_id.

### `create_retell_llm` (~535 tokens)

Create a new Retell LLM response engine with prompt and model settings.

WHEN TO USE:
\- Creating a new agent that needs its own prompt/model config
\- Separating a new call workflow from an existing agent's LLM
\- Testing a new prompt without overwriting a production LLM

WORKFLOW: Create the LLM first, then create_agent with response_engine: { "type": "retell-llm", "llm_id": "<returned llm_id>" }.

EXAMPLE:
{ "general_prompt": "You confirm appointment times and answer basic scheduling questions.", "begin_message": "Hi, I'm calling to confirm your appointment.", "model": "gpt-5.5" }

MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite.

COMMON MISTAKES:
\- Creating multiple near-identical LLMs instead of updating the existing one
\- Creating the LLM but never attaching it to an agent

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 422: invalid model/prompt → use a listed model and non-empty prompt

RELATED TOOLS:
\- list_retell_llms/get_retell_llm: Reuse or inspect existing configs
\- create_agent/update_agent: Attach the new llm_id to an agent
\- update_retell_llm: Modify this config later

RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.

Input parameters:

- `begin_message` (string): First message spoken when the call connects.
- `general_prompt` (string): System prompt/instructions for the voice agent. Keep it call-ready and explicit.
- `model` (string): LLM model. Options: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite.

### `list_retell_llms` (~270 tokens)

List all Retell LLM response engine configurations.

WHEN TO USE:
\- Find llm_id values before get_retell_llm/update_retell_llm
\- Inventory prompt/model configurations
\- Decide whether to reuse an LLM or create a new one

COMMON MISTAKES:
\- Updating an arbitrary llm_id without checking which agent uses it
\- Assuming list order implies which LLM is active; use get_agent to confirm bindings

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 422: invalid pagination params → keep limit between 1 and 1000

RELATED TOOLS:
\- get_retell_llm: Inspect one returned llm_id
\- update_retell_llm: Change prompt/model
\- get_agent/list_agents: See which agents reference each LLM
\- create_retell_llm: Create a separate config when reuse is unsafe

RETURNS: llms, count, pagination_key, has_more. Each LLM includes llm_id, prompt/model fields, and timestamps when available.

Input parameters:

- `limit` (integer): Max results to return (default: 50, max: 1000).
- `pagination_key` (string): Pagination key from the previous response for the next page.

### `list_voices` (~175 tokens)

Browse all available TTS voices in Retell.

WHEN TO USE:
\- Find voice IDs when creating or updating an agent
\- Compare providers/voice names before selecting a voice
\- Verify a voice_id still exists after a 404 from create_agent/update_agent

COMMON MISTAKES:
\- Passing the display name instead of the exact voice_id
\- Reusing an old voice_id without checking it still exists

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key

RELATED TOOLS:
\- create_agent: Use a returned voice_id for a new agent
\- update_agent: Change an existing agent's voice_id

RETURNS: voices, count. Each voice includes voice_id, voice_name/name, provider, accent/language/gender, and preview metadata when available.

### `list_phone_numbers` (~315 tokens)

List all phone numbers in your Retell account with their agent bindings.

WHEN TO USE:
\- Before create_phone_call, to find available from_numbers
\- To check which agents are bound to which numbers
\- To verify outbound agent configuration

TIP: The phone_number field (E.164 format) is what you pass as from_number in create_phone_call.
The outbound_agents array shows which agent(s) are bound for outbound calls from this number.
Check each outbound agent's agent_version before calling; version mismatches are a common 404 cause.

COMMON MISTAKES:
\- Using a number that exists but has no outbound_agents binding
\- Ignoring agent_version on the binding and then overriding only agent_id during create_phone_call

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 422: invalid pagination params → keep limit between 1 and 1000

RELATED TOOLS:
\- get_phone_number: Inspect one number's bindings
\- update_phone_number: Bind or rebind agents
\- create_phone_call: Use returned phone_number as from_number
\- get_agent_versions: Verify bound versions

RETURNS: phone_numbers, count, pagination_key, has_more. Each number includes phone_number, inbound_agents, outbound_agents, nickname/config when available.

Input parameters:

- `limit` (integer): Max results to return (default: 50, max: 1000).
- `pagination_key` (string): Pagination key from the previous response for the next page.

### `get_phone_number` (~248 tokens)

Get details of a specific phone number including its agent bindings.

WHEN TO USE:
\- To check which agents are bound (inbound and outbound) to a specific number
\- To diagnose why create_phone_call returns 404 (missing outbound agent binding)
\- To confirm the bound agent_version before overriding call routing

COMMON MISTAKES:
\- Checking only that the number exists; outbound calls require outbound_agents
\- Missing that the bound agent_version differs from the version you intend to use

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: phone number not found → list_phone_numbers and use the exact E.164 value

RELATED TOOLS:
\- list_phone_numbers: Discover available numbers
\- update_phone_number: Add/fix inbound or outbound bindings
\- get_agent_versions: Verify bound agent versions
\- create_phone_call: Use this phone_number as from_number

RETURNS: phone_number, nickname, inbound_agents, outbound_agents, phone number config fields.

Input parameters:

- `phone_number` (string, required): Phone number in E.164 format exactly as returned by list_phone_numbers (e.g. +14155551234).

### `update_phone_number` (~440 tokens)

Update agent bindings and settings for a phone number.

WHEN TO USE:
\- To bind an agent to a phone number for outbound/inbound calls
\- To fix "404 Not Found" errors on create_phone_call (the number needs an outbound agent)
\- To change which agent handles calls on a number

CRITICAL: After Retell's March 2026 update, phone numbers use weighted agent lists.
Each binding needs agent_id, weight (must sum to 1), and optionally agent_version.

EXAMPLE — bind agent to outbound calls:
{ "phone_number": "+14155551234", "outbound_agents": [{ "agent_id": "agent_xxx", "agent_version": 1, "weight": 1 }] }

COMMON MISTAKES:
\- Omitting agent_version and accidentally binding the wrong/latest version
\- Setting weights that do not sum to 1
\- Updating inbound_agents when the failure is outbound calling

ERROR RECOVERY:
\- 401: API key is missing or invalid → configure_retell_api_key
\- 404: phone_number or agent_id not found → list_phone_numbers/list_agents
\- 422: invalid binding → include agent_id + weight, ensure weights sum to 1, verify agent_version

RELATED TOOLS:
\- get_phone_number/list_phone_numbers: Inspect current bindings first
\- get_agent_versions: Choose a valid agent_version
\- publish_agent: Make the desired version live before binding
\- create_phone_call: Test outbound routing after updating

RETURNS: phone_number, nickname, inbound_agents, outbound_agents, updated config fields.

Input parameters:

- `inbound_agents` (array): Agents for inbound calls. Each item needs agent_id and weight; include agent_version when targeting a specific version. Weights must sum to 1.
- `nickname` (string): Human-readable label for this number.
- `outbound_agents` (array): Agents for outbound calls. Each item needs agent_id and weight; include agent_version to avoid version-binding mistakes. Weights must sum to 1.
- `phone_number` (string, required): Phone number in E.164 format exactly as returned by list_phone_numbers.

### `configure_retell_api_key` (~92 tokens)

Save your Retell AI API key. Call this when the user provides their key.

WHERE TO GET A KEY:
1\. Go to https://www.retellai.com/dashboard
2\. Navigate to API Keys in settings
3\. Create and copy your API key

All other Retell AI tools require a valid API key to work.

Input parameters:

- `api_key` (string, required): Retell AI API key.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai#diagnostics

## Score history

- 2026-08-04: 72
- 2026-08-03: 72
- 2026-08-02: 68
- 2026-08-01: 5
- 2026-07-31: 22
- 2026-07-30: 24
- 2026-07-28: 24
- 2026-07-27: 41

## Links

- npm package: https://www.npmjs.com/package/@mindstone/mcp-server-retell-ai
- Socket report: https://socket.dev/npm/package/@mindstone/mcp-server-retell-ai
- Repository: https://github.com/mindstone/mcp-servers
- Changelog RSS feed: https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai/changelog.json
- HTML version of this page: https://verifymcp.io/servers/mindstone-mcp-server-retell-ai/mindstone-mcp-server-retell-ai