Retell AI MCP Server

Instructions

Implementation Reference

• src/index.ts:1153-1154 (handler)

  The handler logic for the 'retell_create_phone_number' tool, which makes a POST request to the Retell API endpoint '/create-phone-number' using the generic retellRequest helper function.
  case "retell_create_phone_number": return retellRequest("/create-phone-number", "POST", args);
• src/index.ts:313-338 (schema)

  The tool schema definition, including input validation schema, description, and registration in the tools list used by the MCP server.
  { name: "retell_create_phone_number", description: "Register/purchase a new phone number for use with Retell AI agents.", inputSchema: { type: "object", properties: { area_code: { type: "string", description: "The area code for the phone number (e.g., '415' for San Francisco)" }, inbound_agent_id: { type: "string", description: "Optional: Agent ID to handle inbound calls to this number" }, outbound_agent_id: { type: "string", description: "Optional: Agent ID to use for outbound calls from this number" }, nickname: { type: "string", description: "Optional: A friendly name for the phone number" } }, required: ["area_code"] } },
• src/index.ts:1283-1285 (registration)

  The registration of the tool list handler that exposes all tools, including 'retell_create_phone_number', to the MCP protocol.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });
• src/index.ts:1120-1266 (helper)

  The executeTool dispatcher function that handles tool execution based on name, containing the specific case for this tool.
  async function executeTool(name: string, args: Record<string, unknown>): Promise<unknown> { switch (name) { // Call Management case "retell_create_phone_call": return retellRequest("/v2/create-phone-call", "POST", args); case "retell_create_web_call": return retellRequest("/v2/create-web-call", "POST", args); case "retell_get_call": return retellRequest(`/v2/get-call/${args.call_id}`, "GET"); case "retell_list_calls": return retellRequest("/v2/list-calls", "POST", args); case "retell_update_call": { const { call_id, ...updateData } = args; return retellRequest(`/v2/update-call/${call_id}`, "PATCH", updateData as Record<string, unknown>); } case "retell_delete_call": return retellRequest(`/v2/delete-call/${args.call_id}`, "DELETE"); // Chat Management case "retell_create_chat": return retellRequest("/create-chat", "POST", args); case "retell_create_sms_chat": return retellRequest("/create-sms-chat", "POST", args); case "retell_get_chat": return retellRequest(`/get-chat/${args.chat_id}`, "GET"); case "retell_create_chat_completion": return retellRequest("/create-chat-completion", "POST", args); case "retell_list_chats": return retellRequest("/list-chat", "GET"); case "retell_end_chat": return retellRequest("/end-chat", "PATCH", args); // Phone Number Management case "retell_create_phone_number": return retellRequest("/create-phone-number", "POST", args); case "retell_get_phone_number": return retellRequest(`/get-phone-number/${encodeURIComponent(args.phone_number as string)}`, "GET"); case "retell_list_phone_numbers": return retellRequest("/list-phone-numbers", "GET"); case "retell_update_phone_number": { const { phone_number, ...phoneUpdateData } = args; return retellRequest(`/update-phone-number/${encodeURIComponent(phone_number as string)}`, "PATCH", phoneUpdateData as Record<string, unknown>); } case "retell_delete_phone_number": return retellRequest(`/delete-phone-number/${encodeURIComponent(args.phone_number as string)}`, "DELETE"); case "retell_import_phone_number": return retellRequest("/import-phone-number", "POST", args); // Voice Agent Management case "retell_create_agent": return retellRequest("/create-agent", "POST", args); case "retell_get_agent": return retellRequest(`/get-agent/${args.agent_id}`, "GET"); case "retell_list_agents": return retellRequest("/list-agents", "GET"); case "retell_update_agent": { const { agent_id, ...agentUpdateData } = args; return retellRequest(`/update-agent/${agent_id}`, "PATCH", agentUpdateData as Record<string, unknown>); } case "retell_delete_agent": return retellRequest(`/delete-agent/${args.agent_id}`, "DELETE"); case "retell_publish_agent": return retellRequest(`/publish-agent/${args.agent_id}`, "POST"); case "retell_get_agent_versions": return retellRequest(`/get-agent-versions/${args.agent_id}`, "GET"); // Chat Agent Management case "retell_create_chat_agent": return retellRequest("/create-chat-agent", "POST", args); case "retell_get_chat_agent": return retellRequest(`/get-chat-agent/${args.agent_id}`, "GET"); case "retell_list_chat_agents": return retellRequest("/list-chat-agents", "GET"); case "retell_update_chat_agent": { const { agent_id: chatAgentId, ...chatAgentUpdateData } = args; return retellRequest(`/update-chat-agent/${chatAgentId}`, "PATCH", chatAgentUpdateData as Record<string, unknown>); } case "retell_delete_chat_agent": return retellRequest(`/delete-chat-agent/${args.agent_id}`, "DELETE"); // Retell LLM Management case "retell_create_llm": return retellRequest("/create-retell-llm", "POST", args); case "retell_get_llm": return retellRequest(`/get-retell-llm/${args.llm_id}`, "GET"); case "retell_list_llms": return retellRequest("/list-retell-llms", "GET"); case "retell_update_llm": { const { llm_id, ...llmUpdateData } = args; return retellRequest(`/update-retell-llm/${llm_id}`, "PATCH", llmUpdateData as Record<string, unknown>); } case "retell_delete_llm": return retellRequest(`/delete-retell-llm/${args.llm_id}`, "DELETE"); // Conversation Flow Management case "retell_create_conversation_flow": return retellRequest("/create-conversation-flow", "POST", args); case "retell_get_conversation_flow": return retellRequest(`/get-conversation-flow/${args.conversation_flow_id}`, "GET"); case "retell_list_conversation_flows": return retellRequest("/list-conversation-flows", "GET"); case "retell_update_conversation_flow": { const { conversation_flow_id, ...flowUpdateData } = args; return retellRequest(`/update-conversation-flow/${conversation_flow_id}`, "PATCH", flowUpdateData as Record<string, unknown>); } case "retell_delete_conversation_flow": return retellRequest(`/delete-conversation-flow/${args.conversation_flow_id}`, "DELETE"); // Knowledge Base Management case "retell_create_knowledge_base": return retellRequest("/create-knowledge-base", "POST", args); case "retell_get_knowledge_base": return retellRequest(`/get-knowledge-base/${args.knowledge_base_id}`, "GET"); case "retell_list_knowledge_bases": return retellRequest("/list-knowledge-bases", "GET"); case "retell_delete_knowledge_base": return retellRequest(`/delete-knowledge-base/${args.knowledge_base_id}`, "DELETE"); case "retell_add_knowledge_base_sources": { const { knowledge_base_id, sources } = args; return retellRequest(`/add-knowledge-base-sources/${knowledge_base_id}`, "POST", { sources }); } case "retell_delete_knowledge_base_source": { const { knowledge_base_id: kbId, source_id } = args; return retellRequest(`/delete-knowledge-base-source/${kbId}/${source_id}`, "DELETE"); } // Voice Management case "retell_get_voice": return retellRequest(`/get-voice/${args.voice_id}`, "GET"); case "retell_list_voices": return retellRequest("/list-voices", "GET"); // Batch Operations case "retell_create_batch_call": return retellRequest("/create-batch-call", "POST", args); case "retell_create_batch_test": return retellRequest("/create-batch-test", "POST", args); // Account & Telephony case "retell_get_concurrency": return retellRequest("/get-concurrency", "GET"); case "retell_register_phone_call": return retellRequest("/register-phone-call", "POST", args); default: throw new Error(`Unknown tool: ${name}`); }