Retell AI

You can run and interact with the Retell AI API through a dedicated MCP server that exposes a suite of tools for building, testing, deploying, and monitoring AI phone agents. With this server you can manage calls, chats, phone numbers, agents, knowledge bases, and more, all from MCP-compatible clients like Claude. This guide shows you how to install, configure, and use the server end to end.

How to use

You will connect a Claude (or any MCP-compatible) client to the Retell AI MCP server to perform common operations. Start by ensuring the server is running with your API key, then call tools to create and manage calls, chats, numbers, agents, and knowledge bases. You can orchestrate conversations, schedule batch tasks, and publish agent versions from your MCP client by selecting the appropriate tool and supplying the required parameters. Use natural language prompts or tool-specific actions in your client to list resources, retrieve details, or trigger actions such as creating a phone call, starting a chat, or publishing an agent.

Common usage patterns include: finding available voices, creating a voice agent, setting up knowledge bases, and designing LLM configurations and conversation flows. Your MCP client will present the tool set, and you will provide inputs such as IDs, names, prompts, and configuration options to complete each operation.

How to install

Prerequisites you need before starting: Node.js and npm (or an environment that supports running MCP stdio servers). Ensure your environment can run JavaScript/TypeScript builds.

Step 1: Install dependencies and build the MCP server.

Step 2: Start the MCP server as described in the configuration steps below.

Configuration and usage notes

Environment variable you must set: RETELL_API_KEY with your Retell AI API key. This key authenticates requests to Retell AI and enables the MCP server to access endpoints. You can obtain the key from your Retell AI Dashboard.

Two common ways to wire up the MCP server with Claude Code: 1) CLI method and 2) Project configuration file. The CLI method is recommended for quick setup, while the project file helps share configuration across teams.

CLI method: add the MCP server using a stdio transport and provide the API key in the environment.

claude mcp add --transport stdio retell-ai -e RETELL_API_KEY=your-api-key-here -- node /path/to/retell-ai-mcp/dist/index.js
```, and you can also use environment variable expansion.

Environment-variable expansion variant: use the existing RETELL_API_KEY in your shell.

claude mcp add --transport stdio retell-ai -e RETELL_API_KEY=${RETELL_API_KEY} -- node /path/to/retell-ai-mcp/dist/index.js
```, this keeps the key out of the command line and reads it from your environment.

Project configuration file: create a .mcp.json at your project root to share with teammates.

{
  "mcpServers": {
    "retell-ai": {
      "command": "node",
      "args": ["/path/to/retell-ai-mcp/dist/index.js"],
      "env": {
        "RETELL_API_KEY": "${RETELL_API_KEY}"
      }
    }
  }
}
```, this expands the environment variable at runtime.

Claude Desktop configuration

Add the MCP server configuration to Claude Desktop so you can access Retell AI tools from your desktop client. Use the file path appropriate to your OS: macOS or Windows.

{
  "mcpServers": {
    "retell-ai": {
      "command": "node",
      "args": ["/path/to/retell-ai-mcp/dist/index.js"],
      "env": {
        "RETELL_API_KEY": "your-api-key-here"
      }
    }
  }
}
```, place this in the Claude Desktop config at the following paths: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Examples of common operations

You can, for instance, list available voices, create a voice agent, and schedule a batch of outbound calls using the Retell AI MCP server through your MCP client.

Available tools

retell_create_phone_call

Create a new outbound phone call

retell_create_web_call

Create a new web call session

retell_get_call

Retrieve details of a specific call

retell_list_calls

List and filter calls

retell_update_call

Update call metadata

retell_delete_call

Delete a call

retell_create_chat

Create a chat session

retell_create_sms_chat

Start an SMS conversation

retell_get_chat

Get chat details

retell_create_chat_completion

Send a message in a chat and receive a response

retell_list_chats

List all chats

retell_end_chat

End a chat session

retell_create_phone_number

Purchase a phone number

retell_get_phone_number

Get phone number details

retell_list_phone_numbers

List all phone numbers

retell_update_phone_number

Update phone number settings

retell_delete_phone_number

Delete a phone number

retell_import_phone_number

Import a phone number via SIP

retell_create_agent

Create a voice agent

retell_get_agent

Get agent details

retell_list_agents

List all agents

retell_update_agent

Update agent config

retell_delete_agent

Delete an agent

retell_publish_agent

Publish agent version

retell_get_agent_versions

Get version history of an agent

retell_create_chat_agent

Create a chat agent

retell_get_chat_agent

Get chat agent details

retell_list_chat_agents

List chat agents

retell_update_chat_agent

Update chat agent

retell_delete_chat_agent

Delete chat agent

retell_create_llm

Create LLM configuration

retell_get_llm

Get LLM details

retell_list_llms

List all LLMs

retell_update_llm

Update LLM config

retell_delete_llm

Delete LLM

retell_create_conversation_flow

Create a conversation flow

retell_get_conversation_flow

Get flow details

retell_list_conversation_flows

List all conversation flows

retell_update_conversation_flow

Update a conversation flow

retell_delete_conversation_flow

Delete a conversation flow

retell_create_knowledge_base

Create knowledge base

retell_get_knowledge_base

Get knowledge base details

retell_list_knowledge_bases

List all knowledge bases

retell_delete_knowledge_base

Delete knowledge base

retell_add_knowledge_base_sources

Add sources to a knowledge base

retell_delete_knowledge_base_source

Remove a knowledge base source

retell_get_voice

Get voice details

retell_list_voices

List available voices

retell_create_batch_call

Schedule bulk calls

retell_create_batch_test

Run agent tests

retell_get_concurrency

Check concurrent call limits

retell_register_phone_call

Register inbound call