Retell AI MCP Server

Instructions

Implementation Reference

• src/index.ts:1169-1170 (handler)

  Switch case in executeTool function that dispatches the retell_create_agent tool execution by calling the retellRequest helper with the Retell API endpoint for creating an agent.
  case "retell_create_agent": return retellRequest("/create-agent", "POST", args);
• src/index.ts:432-502 (schema)

  Input schema definition for the retell_create_agent tool, specifying parameters like voice_id, response_engine, agent_name, etc., used for validation.
  inputSchema: { type: "object", properties: { voice_id: { type: "string", description: "The voice ID to use for the agent (use retell_list_voices to see available voices)" }, response_engine: { type: "object", description: "The LLM engine configuration. Use type: 'retell-llm' with llm_id, or type: 'conversation-flow' with conversation_flow_id", properties: { type: { type: "string", enum: ["retell-llm", "custom-llm", "conversation-flow"], description: "The type of response engine" }, llm_id: { type: "string", description: "The LLM ID (for retell-llm type)" }, conversation_flow_id: { type: "string", description: "The conversation flow ID (for conversation-flow type)" } }, required: ["type"] }, agent_name: { type: "string", description: "Optional: Display name for the agent" }, language: { type: "string", description: "Language code (e.g., 'en-US', 'es-ES', 'multi' for multilingual)" }, voice_model: { type: "string", enum: ["eleven_turbo_v2", "eleven_flash_v2", "eleven_flash_v2_5", "tts-1", "gpt-4o-mini-tts", "azure", "deepgram", "smallest-ai"], description: "Text-to-speech model to use" }, voice_temperature: { type: "number", description: "Voice naturalness (0-2, default 1)" }, voice_speed: { type: "number", description: "Speech rate (0.5-2, default 1)" }, interruption_sensitivity: { type: "number", description: "How sensitive to user interruptions (0-1)" }, enable_backchannel: { type: "boolean", description: "Enable conversational acknowledgments like 'uh-huh', 'I see'" }, end_call_after_silence_ms: { type: "integer", description: "Milliseconds of silence before ending call" }, max_call_duration_ms: { type: "integer", description: "Maximum call duration in milliseconds" }, webhook_url: { type: "string", description: "URL for receiving call event webhooks" } }, required: ["voice_id", "response_engine"] }
• src/index.ts:430-503 (registration)

  Tool registration object in the tools array, defining name, description, and inputSchema for listing via ListToolsRequestSchema.
  name: "retell_create_agent", description: "Create a new voice agent with specified configuration including voice, LLM engine, and behavior settings.", inputSchema: { type: "object", properties: { voice_id: { type: "string", description: "The voice ID to use for the agent (use retell_list_voices to see available voices)" }, response_engine: { type: "object", description: "The LLM engine configuration. Use type: 'retell-llm' with llm_id, or type: 'conversation-flow' with conversation_flow_id", properties: { type: { type: "string", enum: ["retell-llm", "custom-llm", "conversation-flow"], description: "The type of response engine" }, llm_id: { type: "string", description: "The LLM ID (for retell-llm type)" }, conversation_flow_id: { type: "string", description: "The conversation flow ID (for conversation-flow type)" } }, required: ["type"] }, agent_name: { type: "string", description: "Optional: Display name for the agent" }, language: { type: "string", description: "Language code (e.g., 'en-US', 'es-ES', 'multi' for multilingual)" }, voice_model: { type: "string", enum: ["eleven_turbo_v2", "eleven_flash_v2", "eleven_flash_v2_5", "tts-1", "gpt-4o-mini-tts", "azure", "deepgram", "smallest-ai"], description: "Text-to-speech model to use" }, voice_temperature: { type: "number", description: "Voice naturalness (0-2, default 1)" }, voice_speed: { type: "number", description: "Speech rate (0.5-2, default 1)" }, interruption_sensitivity: { type: "number", description: "How sensitive to user interruptions (0-1)" }, enable_backchannel: { type: "boolean", description: "Enable conversational acknowledgments like 'uh-huh', 'I see'" }, end_call_after_silence_ms: { type: "integer", description: "Milliseconds of silence before ending call" }, max_call_duration_ms: { type: "integer", description: "Maximum call duration in milliseconds" }, webhook_url: { type: "string", description: "URL for receiving call event webhooks" } }, required: ["voice_id", "response_engine"] } },
• src/index.ts:23-57 (helper)

  Generic helper function that makes authenticated HTTP requests to the Retell AI API, used by the tool handler to perform the actual agent creation.
  async function retellRequest( endpoint: string, method: string = "GET", body?: Record<string, unknown> ): Promise<unknown> { const apiKey = getApiKey(); const headers: Record<string, string> = { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", }; const options: RequestInit = { method, headers, }; if (body && method !== "GET") { options.body = JSON.stringify(body); } const response = await fetch(`${RETELL_API_BASE}${endpoint}`, options); if (!response.ok) { const errorText = await response.text(); throw new Error(`Retell API error (${response.status}): ${errorText}`); } // Handle 204 No Content if (response.status === 204) { return { success: true }; } return response.json(); }
• src/index.ts:14-20 (helper)

  Helper function to retrieve the Retell API key from environment variable, used by retellRequest.
  function getApiKey(): string { const apiKey = process.env.RETELL_API_KEY; if (!apiKey) { throw new Error("RETELL_API_KEY environment variable is required"); } return apiKey; }