Getting started
MCPDial runs AI phone agents. You create an agent (one company voice in one role), route a number to it for inbound calls, or place outbound calls from the dashboard, the REST API or MCP. Every call ends with a record: transcript, outcome, actions, cost and latency.
Concepts
Agent — role, persona, voice, goals, hours and allowed tools, stored as an AgentSpec. Call — one conversation, inbound, outbound or a browser test. Contact — a person with a consent state and an evidence ledger. Calendar — the native scheduler the booking tools use. MCP server — a tool source registered once and allowed per agent.
Your first call
Create an agent in the dashboard (or with POST /api/v1/agents), try it with the test-call button, then:
# Base URL: https://<your-app>/api/v1
# Auth: a workspace API key (dashboard → Settings → API keys; shown once).
curl -X POST https://<your-app>/api/v1/calls \
-H "Authorization: Bearer cv_live_…" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "…", "to": "+41441234567", "consent": { "basis": "form" } }'
# → { "call_id": "…", "status": "dialing" }
# or { "call_id": "…", "status": "scheduled", "scheduled_for": "…" } (outside local hours)Errors
Errors are JSON: { "error": { "code": "…", "message": "…" } }.
| Status | Meaning |
|---|---|
400 | Malformed request — a field is missing or invalid. |
401 | Missing, malformed or revoked API key. |
402 | Not enough credit to reserve the call. |
404 | No such agent, call or number in this workspace. |
422 | The compliance gate refused the call (e.g. consent_required, suppressed, jurisdiction_blocked). |
429 | Rate limit — back off and retry. |