Retell AI

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

Connector by mindstone · GitHub account verified by the MCP Registry

IndexedLicense unknownLocal (stdio)★ 13

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/mindstone-mcp-server-retell-ai

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

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

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list and install config. Checked Oct 25, 2026.

Tools: 16 read · 0 write · 16 delete
Secrets: 1 (API keys, tokens or passwords)
Install scripts: Not scanned yet
Runs as: Node.js package

Tools by what they do 32

Read from the source code; the running server may list different tools.

Read 16 · Look things up without changing anything.

get_agent
get_agent_versions
get_call
get_chat
get_concurrency
get_knowledge_base
get_phone_number
get_retell_llm
list_agents
list_calls
list_chat_agents
list_chats

Show 4 more tools

list_knowledge_bases
list_phone_numbers
list_retell_llms
list_voices

Delete 16 · Delete, drop, revoke or wipe things.

add_knowledge_base_sources
configure_retell_api_key
create_agent
create_batch_call
create_knowledge_base
create_phone_call
create_retell_llm
create_web_call
delete_agent
delete_phone_number
delete_retell_llm
publish_agent

Show 4 more tools

stop_call
update_agent
update_phone_number
update_retell_llm

Secrets and settings it asks for

Secrets: values you paste in that let it act as you.

RETELL_API_KEY

Other settings (environment variables or headers).

MCP_WORKSPACE_PATH

Tools (32)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

add_knowledge_base_sourcescan change or delete data
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 - …
configure_retell_api_keycan change or delete data
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.
create_agentcan change or delete data
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: - Cre…
create_batch_callcan change or delete data
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 ac…
create_knowledge_basecan change or delete data
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…
create_phone_callcan change or delete data
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"…
create_retell_llmcan change or delete data
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 OPTIO…
create_web_callcan change or delete data
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…
delete_agentcan change or delete data
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 retu…
delete_phone_numbercan change or delete data
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_nu…
delete_retell_llmcan change or delete data
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_l…
get_agentread-only
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 - 40…
get_agent_versionsread-only
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 dra…
get_callread-only
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…
get_chatread-only
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 t…

Show 17 more tools

get_concurrencyread-only
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 sur…
get_knowledge_baseread-only
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 documen…
get_phone_numberread-only
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 …
get_retell_llmread-only
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 resp…
list_agentsread-only
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 — cal…
list_callsread-only
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…
list_chat_agentsread-only
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 age…
list_chatsread-only
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": 173568…
list_knowledge_basesread-only
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'…
list_phone_numbersread-only
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_ag…
list_retell_llmsread-only
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 -…
list_voicesread-only
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, c…
publish_agentcan change or delete data
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 i…
stop_callcan change or delete data
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.
update_agentcan change or delete data
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/l…
update_phone_numbercan change or delete data
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 }] } …
update_retell_llmcan change or delete data
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 …

Signals

Stars: 13
Forks: 4
Open issues: 1
Weekly downloads: 42
Last commit (this folder): Aug 6, 2026 (2 months ago)
Last release: Aug 5, 2026 (2 months ago)
Last package publish: Aug 5, 2026 (2 months ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name: io.github.mindstone/mcp-server-retell-ai
Version: 0.3.0
Auth: API key
Packages: npm @mindstone/mcp-server-retell-ai
License: License unknown
Repository: github.com/mindstone/mcp-servers
First seen: Oct 24, 2026
Last checked: Oct 24, 2026
Source: Official MCP Registry github-graphql

More from mindstone

Cite this page

Retell AI MCP server. Agent Mart. https://agentmart.dev/connectors/mindstone-mcp-server-retell-ai (last updated 2026-10-24)