retell_create_phone_call

Initiate outbound AI phone calls using registered numbers and configured agents for automated voice interactions.

Instructions

Create a new outbound phone call using Retell AI. Initiates a call from a registered phone number to a target number using a configured AI agent.

Input Schema

TableJSON Schema

Name	Required	Description
`from_number`	Yes	The caller's phone number in E.164 format (e.g., +14157774444). Must be a number registered with Retell.
`to_number`	Yes	The recipient's phone number in E.164 format (e.g., +12137774445)
`override_agent_id`	No	Optional: Specific agent ID to use for this call instead of the number's default agent
`metadata`	No	Optional: Custom metadata to attach to the call for tracking purposes
`retell_llm_dynamic_variables`	No	Optional: Dynamic variables to pass to the LLM for personalized responses

Implementation Reference

src/index.ts:1123-1124 (handler)
The execution handler for the retell_create_phone_call tool. It calls the retellRequest helper to POST the input arguments to the Retell API endpoint /v2/create-phone-call.
```
case "retell_create_phone_call":
  return retellRequest("/v2/create-phone-call", "POST", args);
```

src/index.ts:65-89 (schema)

Input schema defining the parameters for creating a phone call: required from_number and to_number, optional override_agent_id, metadata, and retell_llm_dynamic_variables.

inputSchema: {
  type: "object",
  properties: {
    from_number: {
      type: "string",
      description: "The caller's phone number in E.164 format (e.g., +14157774444). Must be a number registered with Retell."
    },
    to_number: {
      type: "string",
      description: "The recipient's phone number in E.164 format (e.g., +12137774445)"
    },
    override_agent_id: {
      type: "string",
      description: "Optional: Specific agent ID to use for this call instead of the number's default agent"
    },
    metadata: {
      type: "object",
      description: "Optional: Custom metadata to attach to the call for tracking purposes"
    },
    retell_llm_dynamic_variables: {
      type: "object",
      description: "Optional: Dynamic variables to pass to the LLM for personalized responses"
    }
  },
  required: ["from_number", "to_number"]

src/index.ts:62-91 (registration)

Registration of the retell_create_phone_call tool in the tools array used by the MCP server's listTools handler.

{
  name: "retell_create_phone_call",
  description: "Create a new outbound phone call using Retell AI. Initiates a call from a registered phone number to a target number using a configured AI agent.",
  inputSchema: {
    type: "object",
    properties: {
      from_number: {
        type: "string",
        description: "The caller's phone number in E.164 format (e.g., +14157774444). Must be a number registered with Retell."
      },
      to_number: {
        type: "string",
        description: "The recipient's phone number in E.164 format (e.g., +12137774445)"
      },
      override_agent_id: {
        type: "string",
        description: "Optional: Specific agent ID to use for this call instead of the number's default agent"
      },
      metadata: {
        type: "object",
        description: "Optional: Custom metadata to attach to the call for tracking purposes"
      },
      retell_llm_dynamic_variables: {
        type: "object",
        description: "Optional: Dynamic variables to pass to the LLM for personalized responses"
      }
    },
    required: ["from_number", "to_number"]
  }
},

src/index.ts:23-57 (helper)

Helper function retellRequest that performs authenticated HTTP requests to the Retell API, used by the tool handler.

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

Retell AI MCP Server