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}`);
    }