create_voice_agent

Programmatically create a new AI receptionist voice agent.

Voice Agent ManagementPermission: admin

Overview

Creates a fully configured AI receptionist. Under the hood this provisions a Twilio phone number, creates a Retell AI voice agent, connects them, stores the configuration in your project database, and optionally sets up default automations (appointment booking, FAQ responses, call transfers). The agent is typically ready to receive calls in ~30 seconds.

POSTtools/create_voice_agent

Parameters

Parameter	Type	Description
`client_id`required	`uuid`	The unique identifier of the client organization this agent belongs to.
`name`required	`string`	A human-readable name for the voice agent (e.g. "Main Office Receptionist").
`voice_id`required	`string`	The Retell AI voice ID to use for speech synthesis. Browse available voices in the dashboard.
`language`	`string`	BCP-47 language code for the agent.Default: `en-US`
`greeting`required	`string`	The initial greeting the agent speaks when answering a call (e.g. "Thank you for calling Acme Dental, how can I help you today?").
`system_prompt`required	`string`	Instructions that define the agent's persona, behavior, and knowledge boundaries.
`services`required	`string[]`	Array of service names the business offers that the agent can discuss and book (e.g. ["Teeth Cleaning", "Root Canal", "Consultation"]).
`business_hours`required	`object`	Weekly schedule object with day keys (mon-sun) mapping to { open, close } time strings in 24h format, or null for closed days.
`escalation_rules`	`object`	Rules for when the agent should transfer calls to a human. Includes transfer_number, conditions (e.g. angry caller, billing dispute), and max_attempts before auto-transfer.
`faq`	`array`	Array of { question, answer } objects the agent can reference during calls to provide consistent answers.
`phone_area_code`	`string`	Preferred area code for the provisioned phone number (e.g. "415"). Best-effort; falls back to same region if unavailable.
`phone_country`	`string`	ISO 3166-1 alpha-2 country code for phone number provisioning.Default: `US`

Permissions

This tool requires admin permission. Service-role or member-level API keys will receive a 403 error.

Provisioning lifecycle

Phone number provisioning takes 5-15 seconds. The agent status starts as provisioning and transitions to active once the Twilio number is connected and verified. If provisioning fails, status will be set to error with details available in the metadata.error field.

Example

Create a dental office receptionisttypescript

const result = await mcp.callTool("create_voice_agent", {
  client_id: "c_8f14e45f-ceea-467f-a83c-01b45c55a86a",
  name: "Acme Dental Receptionist",
  voice_id: "voice_female_professional_01",
  language: "en-US",
  greeting: "Thank you for calling Acme Dental! How can I help you today?",
  system_prompt: "You are a friendly, professional receptionist for Acme Dental. Help callers schedule appointments, answer questions about services and insurance, and transfer to staff when needed. Always confirm appointment details before booking.",
  services: ["Teeth Cleaning", "Root Canal", "Whitening", "Consultation", "Emergency Visit"],
  business_hours: {
    mon: { open: "08:00", close: "17:00" },
    tue: { open: "08:00", close: "17:00" },
    wed: { open: "08:00", close: "17:00" },
    thu: { open: "08:00", close: "19:00" },
    fri: { open: "08:00", close: "15:00" },
    sat: null,
    sun: null
  },
  escalation_rules: {
    transfer_number: "+15551234567",
    conditions: ["billing dispute", "medical emergency", "angry caller"],
    max_attempts: 3
  },
  faq: [
    { question: "Do you accept insurance?", answer: "Yes, we accept most major dental insurance plans including Delta Dental, Cigna, and Aetna." },
    { question: "Where are you located?", answer: "We are at 123 Main Street, Suite 200, San Francisco, CA 94102." }
  ],
  phone_area_code: "415",
  phone_country: "US"
});

Response

200 OK

{
  "agent": {
    "id": "va_01hxk9m3",
    "client_id": "c_8f14e45f-ceea-467f-a83c-01b45c55a86a",
    "name": "Acme Dental Receptionist",
    "voice_id": "voice_female_professional_01",
    "language": "en-US",
    "greeting": "Thank you for calling Acme Dental! How can I help you today?",
    "phone_number": "+14155550199",
    "status": "provisioning",
    "services": ["Teeth Cleaning", "Root Canal", "Whitening", "Consultation", "Emergency Visit"],
    "business_hours": {
      "mon": { "open": "08:00", "close": "17:00" },
      "tue": { "open": "08:00", "close": "17:00" },
      "wed": { "open": "08:00", "close": "17:00" },
      "thu": { "open": "08:00", "close": "19:00" },
      "fri": { "open": "08:00", "close": "15:00" },
      "sat": null,
      "sun": null
    },
    "escalation_rules": {
      "transfer_number": "+15551234567",
      "conditions": ["billing dispute", "medical emergency", "angry caller"],
      "max_attempts": 3
    },
    "faq": [
      { "question": "Do you accept insurance?", "answer": "Yes, we accept most major dental insurance plans including Delta Dental, Cigna, and Aetna." },
      { "question": "Where are you located?", "answer": "We are at 123 Main Street, Suite 200, San Francisco, CA 94102." }
    ],
    "created_at": "2025-06-10T14:30:00Z"
  }
}

create_voice_agent

Overview

Parameters

Example

Response

Search Documentation