@jesec/retellai-mcp-server/README.md

Model Context Protocol server for Retell AI - Make outbound calls with AI agents

# Retell AI MCP Server

A Model Context Protocol (MCP) server for Retell AI, enabling AI assistants to make outbound calls and interact with voice services.

## Features

The Retell AI MCP server provides tools for:

- **Call Management**: Create and manage outbound phone calls and web calls
- **Agent Management**: Create voice agents with customizable LLM configurations
- **LLM Configuration**: Design custom prompts for any use case - from restaurant reservations to complex customer service
- **Phone Number Management**: List and manage your Retell phone numbers
- **Voice Management**: Choose from various voice options for your agents

## Claude Desktop Setup

1. Open `Claude Desktop` and press `CMD + ,` to go to `Settings`.
2. Click on the `Developer` tab.
3. Click on the `Edit Config` button.
4. This will open the `claude_desktop_config.json` file in your file explorer.
5. Get your Retell API key from the Retell dashboard (<https://dashboard.retellai.com/apiKey>).
6. Add the following to your `claude_desktop_config.json` file. See [here](https://modelcontextprotocol.io/quickstart/user) for more details.
7. Restart the Claude Desktop after editing the config file.

```json
{
  "mcpServers": {
    "retellai-mcp-server": {
      "command": "npx",
      "args": ["-y", "@jesec/retellai-mcp-server"],
      "env": {
        "RETELL_API_KEY": "<your_retellai_token>"
      }
    }
  }
}
```

## ⚠️ CRITICAL: Think Before You Call - Information Gathering

**NEVER skip the information gathering phase!** But be INTELLIGENT about what information you need.

### 🧠 Think From the Recipient's Perspective

Before making any call, ask yourself: **"What would the person answering this call need to know to help me?"**

Every situation is unique. A call to emergency roadside assistance needs different information than a call to order flowers. Think deeply about the specific context.

### Core Principle: Context-Aware Information Gathering

Instead of following rigid checklists, consider:
1. **Who you're calling** - Business type, formality level, industry norms
2. **What they need to know** - Think like the person answering
3. **What ensures success** - Critical info vs nice-to-have details

### Examples of Intelligent Context Thinking

- **Pizza order** → Size, toppings, delivery address, timing
- **Car breakdown** → Location, vehicle info, safety status, insurance
- **Passport inquiry** → Specific question, current application status, deadlines
- **Dentist emergency** → Pain level, duration, previous patient status
- **School enrollment** → Child's age, district, special needs, documentation
- **Legal consultation** → Matter type, urgency, how you found them
- **Plumber emergency** → Problem description, property access, water shut-off location
- **Restaurant complaint** → Order details, date/time, specific issue, desired resolution

Notice how each situation requires DIFFERENT information based on context!

### ✅ SMART Workflow:
1. User: "Order a pizza"
2. You: Think what pizza place needs → Ask contextually relevant questions
3. User: Provides information
4. You: Notice if anything crucial is missing, ask follow-ups if needed
5. You: Create call with complete, context-appropriate information
6. Result: Natural, successful conversation!

### ❌ COMMON Mistakes:
- Using the same questions for every call type
- Not thinking about recipient's actual needs
- Missing context-specific critical information
- Over-gathering irrelevant details for simple calls

## ⚠️ CRITICAL: Never Trust Agent Names!

### The "Pizza Agent" Trap

Just because an agent is named "Pizza Order Agent" doesn't mean it will work for YOUR pizza order!

**Why this is dangerous:**
- A "Pizza Agent" might be configured for a SPECIFIC restaurant only
- It could have hardcoded addresses, menu items, or phone numbers
- The prompt might be completely wrong for your current needs
- It might be an old test agent that doesn't work properly

### ✅ ALWAYS Verify Agents Before Using:

1. **List agents** - See what's available
2. **Check the name** - But don't trust it!
3. **Use get_agent** - Inspect the actual configuration
4. **Use get_retell_llm** - Read the ACTUAL PROMPT to understand behavior
5. **Verify it matches** - Ensure it fits YOUR specific needs

### Example Verification Flow:

```
User: "Order a pizza from Domino's"
AI: Let me check what agents exist...
    *Uses list_agents*
AI: I see a "Pizza Order Agent" - let me verify it...
    *Checks with get_agent and get_retell_llm*
AI: This agent is hardcoded for Pizza Hut, not Domino's!
AI: Let me check for other agents...
    *Finds no suitable generic agent*
AI: I'll need to create a new agent for this task...
    *Creates new LLM config and agent*
```

**Remember:**
- Agent names are just labels - always verify!
- Don't assume a "generic" or "general" agent exists
- You may need to create a new agent from scratch

## ⚠️ CRITICAL: Variable Matching Must Be EXACT!

### The Variable Mismatch Disaster

**THE #1 CAUSE OF CALL FAILURES:** Using wrong variable names or passing variables when none are expected!

### How Variables Work in Retell:
1. **Agent prompts contain {{VARIABLE_NAME}} placeholders**
2. **You MUST pass EXACTLY those variable names**
3. **If NO variables in prompt → Pass empty object {}**
4. **Variable names are CASE-SENSITIVE**

### Common Failures:

❌ **Prompt has NO variables, but you pass data:**
```json
// Prompt: "Call pizza place and order large pepperoni" (no {{variables}})
"retellLlmDynamicVariables": {"TASK": "order pizza"}  // IGNORED!
```

❌ **Wrong variable names:**
```json
// Prompt contains: {{ORDER}} and {{CUSTOMER}}
"retellLlmDynamicVariables": {"TASK": "...", "DETAILS": "..."}  // FAILS!
```

❌ **Missing required variables:**
```json
// Prompt contains: {{NAME}}, {{PHONE}}, {{ADDRESS}}
"retellLlmDynamicVariables": {"NAME": "John"}  // INCOMPLETE!
```

### ✅ CORRECT Variable Matching:

1. **Check the prompt first:**
   ```
   Use get_retell_llm to see EXACT variable names
   ```

2. **Match exactly:**
   ```json
   // If prompt has {{TASK}} and {{INFO}}:
   "retellLlmDynamicVariables": {
     "TASK": "your task here",
     "INFO": "your info here"
   }

   // If prompt has NO variables:
   "retellLlmDynamicVariables": {}
   ```

**ALWAYS verify what variables the agent expects BEFORE making the call!**

## Example Use Cases

### Basic Operations
- List all phone numbers available
- List all existing agents
- Get details about a specific agent

### Making Outbound Calls

1. **Restaurant Reservations**
   - Create an agent to make dinner reservations
   - Handle IVR navigation and voicemail
   - Confirm details and get confirmation numbers

2. **Medical Appointments**
   - Schedule doctor appointments
   - Handle HIPAA verification
   - Navigate insurance discussions

3. **Customer Service**
   - Inquire about bills or services
   - Handle account verification
   - Navigate complex IVR systems

4. **Custom Scenarios**
   - Government services (DMV, permits)
   - Travel bookings (hotels, flights)
   - Home services (repairs, deliveries)
   - And many more - the examples provided are just starting points!

### Creating Custom Agents

The MCP server includes comprehensive prompt examples but encourages creativity:
- Mix and match elements from different examples
- Create industry-specific agents
- Experiment with different models (GPT-4o, Claude, Gemini, DeepSeek)
- Design prompts for your unique requirements

Example workflow:
1. Create a custom LLM configuration with your specific prompt
2. Create an agent using that LLM
3. Get your phone number from the list
4. Make the outbound call with dynamic variables
5. Monitor the call status and get results

## Repo Setup

1. Install dependencies:

   ```bash
   npm i
   ```

2. Create a `.env` file with your RetellAI API key:

   ```
   RETELL_API_KEY=your_api_key_here
   ```

3. Run the server:
   ```bash
   node src/retell/index.js
   ```

## Available Tools

### Call Tools

- `list_calls`: Lists all Retell calls
- `create_phone_call`: Creates a new phone call
- `create_web_call`: Creates a new web call
- `get_call`: Gets details of a specific call
- `delete_call`: Deletes a specific call

### Agent Tools

- `list_agents`: Lists all Retell agents
- `create_agent`: Creates a new Retell agent
- `get_agent`: Gets a Retell agent by ID
- `update_agent`: Updates an existing Retell agent
- `delete_agent`: Deletes a Retell agent
- `get_agent_versions`: Gets all versions of a Retell agent

### Phone Number Tools

- `list_phone_numbers`: Lists all Retell phone numbers
- `create_phone_number`: Creates a new phone number
- `get_phone_number`: Gets details of a specific phone number
- `update_phone_number`: Updates a phone number
- `delete_phone_number`: Deletes a phone number

### Voice Tools

- `list_voices`: Lists all available Retell voices
- `get_voice`: Gets details of a specific voice

## License

MIT