AgentPhone MCP Server
OfficialAgentPhone MCP server gives an AI agent its own phone lines — buy numbers, text, and place AI-driven or webhook-driven calls, all governed by agents it can configure.
Agents — create, update, delete, and inspect agents with voices, system prompts, greetings, voicemail, call transfer, language, model tier, and voice tuning; attach or detach phone numbers.
Phone numbers — list numbers and buy new ones (US/CA, optional area code), with a
confirm=trueguard on purchases.Messaging — send SMS/iMessage (text, media, threaded replies, effects, reactions, group posts) and read messages, conversations, and full thread history.
Voice calls — place outbound calls either webhook-driven (
make_call) or with built-in autonomous AI conversation (make_conversation_call), then fetch call details, transcripts, and status.Contacts — list, search, create, update, and delete saved contacts.
Webhooks — get/set/delete project-level or per-agent webhooks, send test events, and review delivery history.
Account & billing — snapshot the account and pull usage/cost breakdowns by day or month.
Voices — browse available voice IDs to assign to agents.
Note: outbound calls and messages are previewed first and only execute with confirm=true, and no call audio or recordings are ever returned.
Allows sending iMessage messages with support for media, threaded replies, send effects, and group chats.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AgentPhone MCP Server Buy me a phone number in the 415 area code"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AgentPhone MCP Server
Give AI agents real phone numbers, SMS, and voice calls via the Model Context Protocol.
AgentPhone lets your AI agent buy phone numbers, send/receive SMS, and place voice calls — all through natural language in Cursor, Claude Desktop, or any MCP-compatible client.
Agents are the core concept — each agent gets its own phone numbers, voice personality, system prompt, and webhook. Think of an agent as a virtual team member with its own phone line. You can create agents for different purposes (support, sales, scheduling) and configure how they sound and behave on calls.
Quick Start
1. Get your API key
Sign up at agentphone.ai and create an API key from Settings.
2. Connect via MCP
Option A: Remote server (recommended)
Point your MCP client at the hosted endpoint — no install needed:
{
"mcpServers": {
"agentphone": {
"type": "streamable-http",
"url": "https://mcp.agentphone.ai/mcp",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}Works with any MCP client that supports Streamable HTTP transport (Switchboard, remote agent platforms, etc.).
Option B: Local server (stdio)
Runs locally via npx — works with Cursor, Claude Desktop, Windsurf, and Claude Code:
Cursor: Settings > MCP or ~/.cursor/mcp.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"agentphone": {
"command": "npx",
"args": ["-y", "agentphone-mcp"],
"env": {
"AGENTPHONE_API_KEY": "your_api_key_here"
}
}
}
}Option C: Self-hosted HTTP server
Run your own HTTP MCP endpoint:
PORT=3000 npx agentphone-mcp --httpThen connect to http://localhost:3000/mcp and configure your MCP client to send
Authorization: Bearer <your AgentPhone API key> with each request. A server-side
AGENTPHONE_API_KEY alone does not authorize HTTP callers.
Warning: AGENTPHONE_ALLOW_ANONYMOUS=true opts into using the server's
AGENTPHONE_API_KEY for requests with no Authorization header, only when OAuth
is off. Anyone who can reach that endpoint can act as the account: only enable
this behind your own authentication. Malformed headers are rejected, and a
caller's supplied bearer is never replaced by the server key.
Related MCP server: agentline-mcp
What Can It Do?
Once configured, just ask your AI agent things like:
"Buy me a phone number in the 415 area code"
"Create a support agent that greets callers and helps with billing"
"Call +14155551234 and have a conversation about scheduling a dentist appointment"
"Text +14155551234 saying 'Your appointment is confirmed for 3pm tomorrow'"
"Show me my recent calls and transcripts"
"List the available voices and switch my agent to a different one"
"Set up a webhook so I get notified when someone calls or texts my number"
"Show me this month's usage breakdown"
Transport & hosting
The server ships two transports from one entry point (node dist/index.js):
stdio (default): bare
npm start/npx agentphone-mcpruns the standard MCP stdio transport for local clients, usingAGENTPHONE_API_KEY.HTTP: set
PORT(or pass--http, optionally with--port <n>) to run the Streamable HTTP server, reachable at/mcp.--portalone does not switch transports —--httporPORTselects HTTP. The HTTP layer is built on the mcp-use framework, which owns Streamable HTTP, the SSE stream, session management, and the OAuth discovery endpoints.Hosted:
https://mcp.agentphone.ai/mcpSelf-hosted HTTP:
PORT=3000 npm start→http://localhost:3000/mcp
Authentication
OAuth (recommended for end users): the framework proxies an Authorization Code + PKCE flow to the AgentPhone authorization server, so the client opens a browser to sign in at agentphone.ai — no key to paste. Enable it by setting
MCP_OAUTH_CLIENT_ID(a client pre-registered with the AgentPhone AS).MCP_OAUTH_CLIENT_SECRETis optional: set it to run the gateway as a confidential client, or leave it unset to run as a public client (the gateway must then be registered withtoken_endpoint_auth_method=none). Public mode advertisesnoneto downstream clients, which strict OAuth clients require.API key (scripts / single-tenant, OAuth off): each request sends
Authorization: Bearer <your API key>. The server-sideAGENTPHONE_API_KEYis only used for callers that send nothing, and only whenAGENTPHONE_ALLOW_ANONYMOUS=true. Without that flag an unauthenticated call is rejected, so an exposed port cannot act as your account.
With OAuth enabled, bearer tokens are verified through the backend’s /auth/me;
the anonymous opt-in does not bypass that verification.
The caller’s credential is forwarded to the AgentPhone REST API for validation. The optional anonymous mode instead uses the configured server API key.
Environment
Var | Purpose |
| HTTP port (default 3000) |
| Fallback API key when OAuth is off. Only used for callers that send no |
| Default off; ignored when OAuth is enabled. Set to |
| Enable OAuth; a gateway client pre-registered with the AgentPhone AS |
| Optional. Set = confidential gateway; unset = public client (gateway registered with |
| API base (default |
| Override authorize/consent URL (default |
| Public base URL this server is reached at, advertised in the |
| Optional, HTTP only, with |
| Optional, HTTP only, with |
Support matrix
Dimension | Supported |
Transports | stdio (default) and Streamable HTTP (set |
Tested runtime | Node |
Clients | Any MCP client — verified with Cursor, Claude Desktop, Claude Code, Windsurf (stdio); Streamable-HTTP clients and remote agent platforms (HTTP) |
Auth modes | stdio: |
Channels | SMS and iMessage (send/receive); voice calls (webhook-driven or built-in AI) |
Number types | US and Canada numbers |
Highlights
Phone numbers — buy and manage numbers in any US/CA area code
SMS — send and receive text messages, view conversation threads
Voice calls — place outbound calls with built-in AI conversation (no webhook needed) or bring your own webhook
Inbound handling — set up webhooks to receive and respond to inbound calls and texts in real time
Agents — create agents with custom voices, system prompts, call transfer, and voicemail
Usage & billing — monitor number usage, message/call/webhook volume, and daily/monthly breakdowns
Authorization & safety
Every outbound call and message is individually authorized by the user.
make_call,make_conversation_call, andsend_messagedo nothing unlessconfirm=trueis passed — without it they return a preview of the full destination(s) and content (all group recipients, the complete message body, every media URL, and any interactive payload) for the user to approve first (the same two-step patternbuy_numberuses). There is no bulk-send path that skips a person in the loop.Greetings and prompts are sent as provided. The connector passes your greeting, topic, system prompt, opening line, and voicemail to the API as you write them, without adding wording of its own. You are responsible for any AI self-identification your use case or jurisdiction requires — put it in the greeting or the agent's instructions (e.g. a greeting that opens with "Hi, I'm Jordan's AI assistant calling to confirm your appointment").
No audio is exposed. Voice synthesis happens only inside live calls; no tool returns audio files or call recordings. (
list_voicesincludes a static voice-samplepreview_audio_url, which is a library clip, not call audio.)
All Tools (32)
Account
Tool | Description |
| Get a full snapshot of your account — agents, numbers, webhook, and usage |
| Get usage stats — number usage, billed SMS segments, and message/call/webhook volume. Use |
Phone Numbers
Tool | Description |
| List all phone numbers in your account |
| Purchase a new phone number with optional |
SMS
Tool | Description |
| Send SMS, iMessage, or WhatsApp. Requires |
| Check which channels a phone number can receive (iMessage / SMS / RCS) before sending |
| Check a number is ready before sending/calling: active + assigned + channel-capable are hard blockers; A2P/10DLC registration and recipient reachability are warnings. Returns |
| Get messages for a specific number. Page older history with |
| List SMS conversations. Pass |
| Get a conversation with a bounded tail of recent messages |
| Page through a conversation's full message history with |
| Set metadata on a conversation |
Contacts
Tool | Description |
| List saved contacts (address book). Filter with a |
| Create, update, or delete a contact (set |
Voice Calls
Tool | Description |
| List calls. Scope by |
| Get call details and transcript, including end reason, failure reason when available, and whether a recording is available (the recording audio/link is never exposed) |
| End an in-progress call (safe to retry; ending a finished call is a no-op) |
| Place an outbound call (webhook-driven). Requires |
| Place a call with built-in AI conversation — no webhook needed. Requires |
Agents
Tool | Description |
| List all agents with their numbers and voice config |
| Create an agent with voice, system prompt, call transfer, voicemail, call-screening identity/purpose, and voice tuning (speed, interruption sensitivity, backchannel, language, and more) |
| Update an agent's configuration (incl. call-screening identity/purpose) |
| Delete an agent (numbers are kept but unassigned) |
| Get agent details including phone numbers and voice config |
| Assign a phone number to an agent |
| Remove a phone number from an agent |
| List available voices for agents |
Webhooks
All webhook tools accept an optional agent_id — pass it to manage an agent-specific webhook, omit it for the project-level default. Agent webhooks take priority over project-level.
Tool | Description |
| Get webhook configuration |
| Set a webhook URL for inbound messages and call events |
| Remove a webhook |
| Send a test event to verify your webhook works |
| View delivery history for debugging |
get_webhook and set_webhook never return the signing secret, for either scope —
it is always masked, so it can't land in model context, transcripts, or client logs.
Retrieve the secret from the AgentPhone dashboard to verify webhook signatures.
Environment Variables
Variable | Required | Description |
| stdio: yes; HTTP anonymous mode: yes | In HTTP mode, used only with |
| No | Explicit HTTP server-key fallback; default off, ignored when OAuth is enabled. See the self-hosting warning above |
| No | Override the API base URL (defaults to |
| No | Port for HTTP mode (defaults to |
| No | HTTP only, with |
| No | HTTP only, with |
Development
git clone https://github.com/AgentPhone-AI/agentphone-mcp.git
cd agentphone-mcp
npm install
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm start # Run compiled JS — stdio by default; set PORT (or pass --http) for the HTTP server
npm test # Build + run the full test suite (both transports, output-schema contracts)Release & deployment checks
Command | What it verifies |
| Version is identical across |
| Runs |
| Fetches the live OpenAPI and asserts the endpoints/fields the tools depend on still exist (message cursors + item fields, call filters, outbound-call request/response fields the client uses, the detach endpoint, and the |
| Read-only post-deploy canary: connects to |
How It Works
This MCP server connects your AI assistant to the AgentPhone API. Your assistant talks to the MCP server, which calls the AgentPhone API, which talks to the phone network.
Your AI Assistant <--> agentphone-mcp <--> AgentPhone API <--> Phone NetworkOutbound: your assistant places calls and sends texts through AgentPhone's API.
Inbound: when someone calls or texts your number, AgentPhone sends a webhook event to your server — you can then respond programmatically or let your agent's built-in AI handle it.
License
MIT
Available Tools
28 toolsaccount_overviewARead-onlyIdempotentInspect
Get a complete snapshot of your AgentPhone account: agents, phone numbers, webhook status, and usage limits.
Inputs: no named parameters.
attach_numberBIdempotentInspect
Attach a phone number to an agent so the agent handles calls/SMS on that number. Takes an agent ID and a phone number ID.
Inputs: agent_id (required), number_id (required).
buy_numberAInspect
Purchase a new phone number. This is a paid purchase that charges the account's balance. area_code requests a specific region (e.g. '415' for San Francisco); agent_id attaches it on purchase. Requires confirm=true to proceed.
Inputs: confirm, country, agent_id, area_code.
create_agentAInspect
Create a new agent. An agent owns phone numbers and handles calls/SMS.
A newly created agent has no phone number until one is attached. Set voice_mode to 'hosted' with a system_prompt for autonomous AI voice calls, or 'webhook' (default) to forward call transcripts to your webhook URL.
Inputs: name (required), voice, language, stt_mode, +14 more.
delete_agentADestructiveInspect
Delete an agent permanently. Phone numbers attached to it are kept but unassigned. This cannot be undone.
Inputs: agent_id (required).
delete_webhookADestructiveInspect
Remove a webhook. Pass agent_id to remove an agent's webhook (falls back to project default). Omit agent_id to remove the project-level webhook.
Inputs: agent_id.
detach_numberBIdempotentInspect
Detach a phone number from an agent. The number is kept in your account but becomes unassigned.
Inputs: agent_id (required), number_id (required).
get_agentARead-onlyIdempotentInspect
Get details for a specific agent including its phone numbers, voice configuration, and instructions.
Inputs: agent_id (required).
get_callARead-onlyIdempotentInspect
Get details and transcript for a specific call, identified by its call ID. Pass wait=true to block until an in-progress call finishes before returning.
Inputs: call_id (required), wait, timeout.
get_conversationBRead-onlyIdempotentInspect
Get a specific SMS conversation with full message history, identified by its conversation ID.
Inputs: conversation_id (required), message_limit.
get_messagesARead-onlyIdempotentInspect
Get SMS messages for a specific phone number, identified by its number ID. Returns individual messages rather than grouped conversation threads.
Inputs: number_id (required), limit.
get_usageARead-onlyIdempotentInspect
Get account usage statistics. By default returns a summary with number usage plus message, call, and webhook volume. Use breakdown='daily' or 'monthly' for time-series data.
Inputs: days, months, breakdown.
get_webhookARead-onlyIdempotentInspect
Get the webhook configuration. Pass agent_id to get an agent-specific webhook, or omit for the project-level default.
Inputs: agent_id.
list_agentsARead-onlyIdempotentInspect
List all agents with their phone numbers and voice configuration. An agent is required before you can make calls — it owns phone numbers and handles voice/SMS.
Inputs: limit.
list_callsARead-onlyIdempotentInspect
List recent calls. Scope by agent_id or number_id, or use status/direction/search to filter globally.
When agent_id or number_id is passed, status/direction/search filters are not applied. Returns call summaries including each call's ID, direction, participants, and status.
Inputs: limit, offset, search, status, +3 more.
list_contactsARead-onlyIdempotentInspect
List saved contacts (your address book). Optionally filter with a search term that matches name or phone number.
Inputs: limit, offset, search.
list_conversationsARead-onlyIdempotentInspect
List SMS conversations. Optionally filter by agent_id to see conversations for a specific agent.
Each conversation is a thread between your number and an external contact, with its ID, participant, message count, and last-message preview.
Inputs: limit, offset, agent_id.
list_numbersARead-onlyIdempotentInspect
List all phone numbers in your account, each with its ID, status, country, and assigned agent.
Inputs: limit, offset.
list_voicesARead-onlyIdempotentInspect
List available voices for agents. Each voice has a voice_id used in an agent's voice field.
Inputs: no named parameters.
list_webhook_deliveriesARead-onlyIdempotentInspect
View recent webhook delivery history. Shows which events were delivered, HTTP status codes, and timing.
Pass agent_id to see deliveries for that agent's webhook. Omit for project-level.
Inputs: hours, limit, agent_id.
make_callAInspect
Initiate an outbound, webhook-driven phone call where your backend handles the conversation logic.
The agent must have a phone number attached and a webhook configured. Every call automatically opens with an automated-assistant disclosure (added server-side and not removable).
Inputs: agent_id (required), to_number (required), voice, from_number_id, +1 more.
make_conversation_callAInspect
Place a phone call where the AI has an autonomous conversation about a given topic — scheduling, surveys, follow-ups, etc. No webhook setup needed.
The agent must have a phone number attached. Every call automatically opens with an automated-assistant disclosure (added server-side; cannot be disabled via topic or initial_greeting). By default this blocks until the call finishes and returns the full transcript. Set wait=false for fire-and-forget.
Inputs: topic (required), agent_id (required), to_number (required), wait, +4 more.
manage_contactADestructiveInspect
Create, update, or delete a saved contact. Set action to choose the operation.
create: requires phone_number and name
update: requires contact_id; only the fields you pass are changed
delete: requires contact_id (permanent)
contact_id refers to a saved contact.
Inputs: action (required), name, email, notes, +2 more.
send_messageAInspect
Send an SMS or iMessage from one of your agent's phone numbers, or react to a message.
The agent must have at least one phone number attached. If the agent has multiple numbers, number_id or from_number selects which one to send from. iMessage extras (silently ignored on SMS): reply_to_message_id threads the reply under an earlier message, and send_style adds an expressive screen/bubble effect. To react to a message instead of sending one, set reaction and react_to_message_id (iMessage only); to_number and body are not needed in that case.
Inputs: body, agent_id, reaction, media_url, +7 more.
set_webhookAIdempotentInspect
Set a webhook URL to receive inbound messages and call events.
Pass agent_id to set a webhook for a specific agent (overrides project default). Omit agent_id to set the project-level webhook for all agents. The webhook secret is returned — use it to verify signatures.
Inputs: url (required), timeout, agent_id, context_limit.
test_webhookAIdempotentInspect
Send a test event to verify a webhook is working. Returns the HTTP status code and response time.
Pass agent_id to test that agent's webhook. Omit to test the project-level webhook.
Inputs: agent_id.
update_agentAIdempotentInspect
Update an agent's configuration — name, description, voice settings, instructions, greeting, call transfer, or voicemail. Only provided fields are updated. Switching voice_mode to 'hosted' requires a system_prompt.
Inputs: agent_id (required), name, voice, language, +15 more.
update_conversationAIdempotentInspect
Set metadata on a conversation. Use this to store custom state, tags, or context that persists between messages. Pass null to clear metadata.
Inputs: metadata (required), conversation_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools have clearly distinct resource+action targets, and the two call tools (make_call vs make_conversation_call) are well-differentiated by their descriptions. Minor overlap exists in the messaging domain where get_messages (raw per-number messages) could be confused with get_conversation (threaded history), but descriptions clarify the boundary.
The set overwhelmingly follows a consistent verb_noun pattern (list_agents, create_agent, get_webhook, send_message). The main deviations are account_overview (noun-first) and manage_contact (a bundled multi-operation CRUD tool) versus the otherwise granular per-verb style.
28 tools is on the heavy side of the recommended range, though the domain (agents, numbers, calls, SMS, conversations, contacts, webhooks, usage) is genuinely broad. Almost every tool earns its place with little redundancy, but the count pushes into borderline-heavy territory.
Coverage is strong: full CRUD for agents and contacts, complete webhook lifecycle (get/set/delete/test/deliveries), and call/message/conversation operations. The notable gap is the phone-number lifecycle — buy_number exists but there is no release/delete or update number operation.
Maintenance
Related MCP Connectors
Give any AI agent a phone: make and answer calls, get through phone menus, and send texts.
Give AI agents a phone number. Voice calls, SMS, and phone number management for MCP clients.
Give AI agents a phone layer for consent-based calls, transcripts, summaries, and outcomes.
Phone numbers for AI agents: get a number, read texted verification codes, place AI voice calls.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to make real-world phone calls with AI voice technology and provides tools to track call status, transcripts, and summaries. It supports automated communication with both live numbers and simulated businesses for testing and demonstration purposes.MIT
- AlicenseAqualityCmaintenanceGives AI agents phone numbers, email, SMS, and voice calls as MCP tools, enabling them to provision numbers, capture 2FA codes, send messages, and make calls.15MIT
- AlicenseAqualityDmaintenanceGives AI agents real phone numbers to receive SMS and extract verification codes through tool calls.6MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to control PSTN phone calls via TelePath, including dialing, hangup, and phone number management.110 npmMIT