Retell AI

io.github.mindstone由 GitHub 账号 mindstone 发布v0.4.0更新于 Nov 17, 2026

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

概览

AI 生成的概览

将助手接入 Retell AI,用于发起语音智能体电话与网页通话、管理智能体和提示词,并查看通话记录。

可以做什么
  • 发起、监控并终止外呼电话和浏览器语音通话,以及创建批量外呼任务
  • 浏览通话历史,查看通话状态、转录文本、录音和并发额度
  • 创建、更新、发布、版本管理及删除语音智能体
  • 创建和修改 Retell LLM 的提示词与模型配置
  • 管理知识库及其文本、网址或本地文件来源
  • 列出音色、电话号码和聊天智能体,并读取聊天转录
适用场景
适合已在使用 Retell AI 语音智能体、希望由助手完成提示词设置、发起或安排通话并查看通话与聊天结果的场景,通过一个本地连接器完成。
运行要求
以 npx 运行的本地进程,需要 Node.js 20+ 和 npm。必须通过环境变量 RETELL_API_KEY 提供 Retell AI API 密钥。可选设置 MCP_WORKSPACE_PATH,用于限制作为知识库来源上传的本地文件目录。需要访问 Retell AI API 的网络连接。
安装前请注意
外呼和批量外呼是真实且计费的操作,会拨打真实电话;每次通话都应展示主叫与被叫号码并单独确认。删除智能体、LLM 和电话号码不可恢复,号码释放后可能无法取回。更新智能体、发布、修改提示词和重新绑定号码会改变线上通话行为。作为知识库来源上传的本地文件会从工作区目录读取并发送给 Retell。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Retell AI,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@mindstone/mcp-server-retell-ai

[npm version] [License: FSL-1.1-MIT]

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

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):

json
{  "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

[Add to Cursor] [Add to VS Code] [Add to VS Code Insiders]

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

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Retell AI)
json
{  "mcpServers": {    "Retell AI": {      "command": "npx",      "args": [        "-y",        "@mindstone/mcp-server-retell-ai"      ],      "env": {        "RETELL_API_KEY": ""      }    }  }}

Quick Start

Install & build

bash
cd <path-to-repo>/connectors/retell-ainpm installnpm run build

npx

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

Local

bash
node dist/index.js

Configuration

Set the following environment variable:

VariableRequiredDescription
RETELL_API_KEYYesRetell AI API key. Get one at retellai.com/dashboard
MCP_WORKSPACE_PATHNoWorkspace directory for local files uploaded as knowledge-base sources (create_knowledge_base / add_knowledge_base_sources file_paths). Defaults to the system temp directory. For standalone clients, file reads are sandboxed to this directory; for negotiated files/readModes version 1, see Host-authorized local inputs.

MCP Host Configuration

json
{  "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 for standalone clients

create_knowledge_base and add_knowledge_base_sources accept local file_paths. For standalone clients, including clients that do not negotiate files/readModes version 1, 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. With negotiated version 1, the host selects a mode for each call: in central mode, input reads use only the host-authorized canonical path described under Host-authorized local inputs; in standalone mode, the standalone restrictions apply. In every mode, the read itself is open-then-validate: the connector opens a descriptor, confirms the opened inode is the approved file, 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.

Host-authorized local inputs

files/readModes version 1 is an experimental extension used by these connectors, not part of the MCP standard. A compatible host (the app running the connector) decides which input files a tool call may read. The connector opens only the host-approved physical path, after resolving symlinks. The host supplies this permission information with each call; it is not a tool argument you need to set. Missing or invalid permission information, or a file absent from the approved list, stops the read.

Clients that do not negotiate this extension keep the connector's existing standalone file restrictions. This extension changes input-read permissions; existing output destinations, upload formats, size limits and file checks apply.

来源:connectors/retell-ai/README.md,提交 18e7c29

工具

32

create_phone_call

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 → the user adds it in Settings → Connectors in the app; do not ask for it in chat - 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, fro

输入参数metadatato_number必填from_number必填override_agent_idoverride_agent_versionretell_llm_dynamic_variables

create_web_call

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.

输入参数agent_id必填metadataagent_versionretell_llm_dynamic_variables

get_call

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.

输入参数call_id必填

list_calls

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.

输入参数limitagent_idsort_orderpagination_keyfilter_criteria

get_concurrency

Get your account's current call concurrency and limits. WHEN TO USE: - Before create_batch_call or a burst of create_phone_call calls, to check capacity headroom - To decide reserved_concurrency for a batch call (leave room for inbound traffic) - To diagnose 429/rate-limit or call-queuing issues HOW TO READ: concurrency_limit is the max simultaneous calls (base + purchased). current_concurrency is how many calls are live right now. Headroom = concurrency_limit - current_concurrency. If concurrency_burst_enabled, the account may exceed the normal limit up to concurrency_burst_limit with a surcharge. ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key RELATED TOOLS: - create_batch_call: Check headroom before sizing a campaign - list_calls: See which calls are currently occupying capacity RETURNS: current_concurrency, concurrency_limit, base_concurrency, purchased_concurrency, concurrency_purchase_limit, remaining_purchase_limit, reserved_inbound_concurrency, concurrency_burst_enabled, concurrency_burst_limit.

无需输入参数。

stop_call

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.

输入参数call_id必填

create_batch_call

Create a batch of outbound phone calls (a calling campaign) from one from_number to many recipients. WHEN TO USE: - User asks to call a list of people (appointment reminders, follow-ups, re-engagement) - Scheduled outbound campaigns — trigger_timestamp defers the start, call_time_window restricts calling hours CRITICAL: Every task in the batch is a real, billed phone call to a real person. The MCP host MUST surface the full recipient list to the user and get explicit confirmation before invoking this tool. A mistake here rings N phones, not one. WORKFLOW: 1. get_concurrency → confirm the account has headroom for the batch size 2. list_phone_numbers/get_phone_number → confirm from_number has an outbound agent bound 3. update_retell_llm + publish_agent → set and publish the campaign prompt 4. create_batch_call → schedule or start the batch 5. list_calls (filter by agent) → monitor results as calls complete EXAMPLE: { "from_number": "+14155551234", "name": "March reminder campaign", "tasks": [{ "to_number": "+14155559876", "retell_llm_dynamic_variables": { "customer_name": "Jane" } }] } COMMON MISTAKES: - Passing dynamic variables the prompt does not reference; they are silently dropped (check get_retell_llm first) - Forgetting the per-call agent binding: from_number needs an outbound_agents binding (update_phone_number), or each task needs override_agent_id + override_agent_version - Using seconds for trigger_timestamp; Retell expects milliseconds ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 402: payment required → add a payment method in the Retell dashboard - 422: invalid task shape → verify every to_number is E.164 and the from_number is registered RELATED TOOLS: - get_concurrency: Check capacity before sizing the batch - list_phone_numbers/update_phone_number: Verify or fix the outbound binding on from_number - update_retell_llm/publish_agent: Prepare the campaign prompt - list_calls/get_call: Track individual call outco

输入参数nametasks必填from_number必填call_time_windowtrigger_timestampreserved_concurrency

get_agent

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.

输入参数agent_id必填

list_agents

List configured voice agents in your Retell account (paginated). WHEN TO USE: - Discover available agents before making calls - Find agent IDs by name - Inventory check NOTE: Returns summary records (agent_id, agent_name, channel, response_engine_type, voice_id, voice_name, tags, timestamps). Use get_agent for the full configuration of a specific agent. Results are filtered to voice agents; use list_chat_agents for chat agents. COMMON MISTAKES: - Guessing agent IDs from names; use the returned agent_id exactly - Expecting the full agent config here; the list endpoint returns summaries — call get_agent for response_engine.llm_id and version details - Not paginating: pass the returned pagination_key while has_more is true 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 - list_chat_agents: List chat agents instead of voice agents - get_agent_versions: Check published versions - create_phone_call/create_web_call: Use a verified agent_id RETURNS: agents, count, pagination_key, has_more. Each agent summary includes agent_id, agent_name, channel, response_engine_type, voice_id, voice_name, tags, and user_modified_timestamp.

输入参数limitsort_orderpagination_key

create_agent

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.

输入参数languagevoice_idagent_nameresponse_engine

update_agent

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.

输入参数agent_id必填languagevoice_idagent_namevoice_speedambient_soundresponsivenessresponse_engineboosted_keywordsenable_backchannelinterruption_sensitivity

publish_agent

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.

输入参数version必填agent_id必填version_description

delete_agent

Permanently delete an agent and ALL of its versions. WHEN TO USE: - Removing a test/throwaway agent after experiments - Cleaning up agents that are no longer needed CRITICAL: This permanently deletes the agent and every version — there is no undo. Any phone numbers bound to it lose their agent binding. Confirm the agent_id with list_agents/get_agent first, and prefer deleting only after checking no phone number still routes to it (list_phone_numbers). ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent_id not found → list_agents and retry with a returned ID RELATED TOOLS: - list_agents/get_agent: Confirm the exact agent_id before deleting - list_phone_numbers: Check no number still binds the agent - create_agent: Create a replacement RETURNS: ok, message. Retell returns HTTP 204 on success.

输入参数agent_id必填

get_agent_versions

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.

输入参数agent_id必填

update_retell_llm

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.

输入参数modelllm_id必填begin_messagegeneral_toolsgeneral_promptmodel_temperature

get_retell_llm

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.

输入参数llm_id必填

create_retell_llm

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.

输入参数modelbegin_messagegeneral_prompt

delete_retell_llm

Permanently delete a Retell LLM response engine and ALL of its versions. WHEN TO USE: - Removing a test/throwaway LLM config after experiments - Cleaning up unused LLM configs CRITICAL: This permanently deletes the LLM and every version — there is no undo. Any agent whose response_engine.llm_id points at it will break (calls will fail). Check which agents reference it via list_agents/get_agent before deleting. ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: llm_id not found → list_retell_llms and retry with a returned ID RELATED TOOLS: - list_retell_llms/get_retell_llm: Confirm the exact llm_id before deleting - list_agents/get_agent: Check no agent still references the LLM - create_retell_llm: Create a replacement RETURNS: ok, message. Retell returns HTTP 204 on success.

输入参数llm_id必填

list_retell_llms

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.

输入参数limitpagination_key

list_voices

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

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.

输入参数limitpagination_key

get_phone_number

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.

输入参数phone_number必填

update_phone_number

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.

输入参数nicknamephone_number必填inbound_agentsoutbound_agents

delete_phone_number

Delete (release) a phone number from your Retell account. WHEN TO USE: - Releasing a number that is no longer needed (stops its recurring cost) - Cleaning up numbers purchased for a finished campaign CRITICAL: This releases the number back — there is no undo, and you may not be able to get the same number back. Any agents bound to it lose their routing immediately. Confirm with get_phone_number first. 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/get_phone_number: Confirm the number and its bindings first - update_phone_number: Rebind agents instead of releasing the number RETURNS: ok, message. Retell returns HTTP 204 on success.

输入参数phone_number必填

list_knowledge_bases

List all knowledge bases in your Retell account. WHEN TO USE: - Find knowledge_base_id values before attaching them to an agent or LLM - Check processing status of a recently created knowledge base (in_progress → complete) - Inventory check before creating a duplicate COMMON MISTAKES: - Creating a new knowledge base when a suitable one already exists; list first - Attaching a knowledge base whose status is still "in_progress" — wait for "complete" ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key RELATED TOOLS: - get_knowledge_base: Inspect one knowledge base's sources and status - create_knowledge_base: Create when nothing suitable exists - add_knowledge_base_sources: Add documents to an existing knowledge base RETURNS: knowledge_bases, count. Each includes knowledge_base_id, knowledge_base_name, status, sources (when processed), and chunking config.

无需输入参数。

get_knowledge_base

Get details of a specific knowledge base, including its sources and processing status. WHEN TO USE: - Check whether a knowledge base has finished processing (status "complete") - List the documents/URLs/texts a knowledge base contains - Verify a source was added before attaching the knowledge base to an agent ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: knowledge_base_id not found → list_knowledge_bases and retry with a returned ID RELATED TOOLS: - list_knowledge_bases: Discover knowledge_base_id values - add_knowledge_base_sources: Add more documents/URLs/texts RETURNS: knowledge_base_id, knowledge_base_name, status, knowledge_base_sources (type, filename/title/url, source_id), chunking config, auto-refresh settings.

输入参数knowledge_base_id必填

create_knowledge_base

Create a knowledge base (documents/URLs/texts) that agents can ground their answers on via RAG. WHEN TO USE: - Ground a voice agent on company docs, FAQs, or policies - Collect source material before wiring knowledge_base_ids into a Retell LLM or agent WORKFLOW: 1. create_knowledge_base → with texts, URLs, and/or local files 2. Poll get_knowledge_base until status is "complete" 3. Attach the knowledge_base_id to the agent's Retell LLM (knowledge_base_ids) — attach via update_retell_llm general_tools/config or the Retell dashboard SOURCES (at least one recommended; a name-only knowledge base is allowed): - knowledge_base_texts: inline title+text pairs - knowledge_base_urls: public URLs Retell scrapes (set enable_auto_refresh to re-scrape every 12 hours) - file_paths: local files to upload. When connected to a host that authorizes file reads, its path permission decision applies to each path. Standalone clients require files inside the workspace sandbox (MCP_WORKSPACE_PATH, or the system temp directory when unset). Max 25 files, 50MB each. COMMON MISTAKES: - Standalone clients: passing a file path outside MCP_WORKSPACE_PATH (or the system temp directory when unset); it is rejected by the workspace sandbox before any disk read - Expecting immediate availability; processing takes time — poll get_knowledge_base for status "complete" ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 422: invalid source shape → check texts have title+text and URLs are valid http(s) URLs RELATED TOOLS: - list_knowledge_bases/get_knowledge_base: Verify and inspect - add_knowledge_base_sources: Add more sources later RETURNS: knowledge_base_id, knowledge_base_name, status (starts "in_progress").

输入参数file_pathsenable_auto_refreshknowledge_base_name必填knowledge_base_urlsknowledge_base_texts

add_knowledge_base_sources

Add new sources (texts, URLs, or local files) to an existing knowledge base. WHEN TO USE: - Extend a knowledge base with new documents without recreating it - Add a freshly written FAQ/policy file to the agent's grounding material NOTE: At least one of knowledge_base_texts, knowledge_base_urls, or file_paths is required. After adding, the knowledge base re-processes (status "refreshing_in_progress") — poll get_knowledge_base until "complete". ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: knowledge_base_id not found → list_knowledge_bases and retry - 422: invalid source shape → check texts have title+text and URLs are valid RELATED TOOLS: - get_knowledge_base: Confirm the sources landed and processing finished - create_knowledge_base: Create a separate knowledge base instead RETURNS: knowledge_base_id, knowledge_base_name, status, updated sources.

输入参数file_pathsknowledge_base_id必填knowledge_base_urlsknowledge_base_texts

list_chat_agents

List configured chat agents in your Retell account (paginated). WHEN TO USE: - Discover chat agents before reading their chats - Find chat agent IDs by name NOTE: Returns summary records (agent_id, agent_name, channel, tags, timestamps). Results are filtered to chat agents; use list_agents for voice agents. ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key RELATED TOOLS: - list_agents: List voice agents instead - list_chats/get_chat: Read chat transcripts for a returned agent_id RETURNS: agents, count, pagination_key, has_more. Each agent summary includes agent_id, agent_name, channel, tags, and user_modified_timestamp.

输入参数limitsort_orderpagination_key

list_chats

List chat sessions with filtering and pagination. Returns recent chats by default (newest first). WHEN TO USE: - Browse chat history for a chat agent - Find a chat_id before reading its full transcript with get_chat - Review chat volume over a time range 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_chat: Get the full transcript and analysis for a returned chat_id - list_chat_agents: Find chat agent IDs for filtering - list_calls: Voice-call equivalent of this tool RETURNS: chats, count, pagination_key, has_more. Each chat includes chat_id, chat_status, agent_id, timestamps, and metadata.

输入参数limitagent_idsort_orderpagination_keyfilter_criteria

get_chat

Get details of a specific chat including full transcript, per-message breakdown, and analysis. WHEN TO USE: - After list_chats, to read one chat's full transcript - To review chat analysis (summary, sentiment, success) for quality checks ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: chat_id not found → check the ID returned by list_chats RELATED TOOLS: - list_chats: Find chat IDs - get_call: Voice-call equivalent (transcript, recording, analysis) RETURNS: chat_id, chat_status, agent_id, transcript, message_with_tool_calls, chat_analysis, start/end timestamps, metadata.

输入参数chat_id必填

configure_retell_api_key

Host-managed setup only. The user adds the Retell AI API key in Settings → Connectors in the app. Do not ask for or accept the key in chat. 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.

输入参数api_key必填

版本历史

2
  1. v0.4.0最新Nov 16, 2026
  2. v0.3.0Sep 16, 2026

评分

已满足适用检查项的 80%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。