Summary
Gives Claude a real phone line through the AgentPhone API. You get 26 tools covering the full lifecycle: buy numbers in specific area codes, send and receive SMS, place outbound calls with AI conversation built in, create agents with custom voices and system prompts, set up webhooks for inbound handling, and pull usage breakdowns. The agent model is clever: each one gets its own numbers and voice personality, so you can spin up separate lines for support, sales, or scheduling. Works over stdio for Cursor and Claude Desktop, or hit their hosted streamable HTTP endpoint if you're building a multi-user platform. Useful when you need your AI to actually interact with people over the phone network, not just simulate it.
Install to Claude Code
verifiedclaude mcp add --transport http agentphone https://mcp.agentphone.to/mcp --header 'Authorization: YOUR_AUTHORIZATION'Run in your terminal. Add --scope user to make it available in every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Tools
Verified live against the running server on Jun 11, 2026.
verified live26 tools
account_overviewGet a complete snapshot of your AgentPhone account: agents, phone numbers, webhook status, and usage limits. Call this first to orient yourself before using other tools.
Get a complete snapshot of your AgentPhone account: agents, phone numbers, webhook status, and usage limits. Call this first to orient yourself before using other tools.
No parameters — call it with no arguments.
list_numbersList all phone numbers in your account. Each number has an ID needed by other tools (get_messages, attach_number, list_calls).2 params
List all phone numbers in your account. Each number has an ID needed by other tools (get_messages, attach_number, list_calls).
Parameters* required
limitnumberMax results to returndefault: 20
offsetnumberNumber of results to skip (for pagination)default: 0
buy_numberPurchase a new phone number. Use area_code to request a specific region (e.g. '415' for San Francisco). Tip: pass agent_id to attach it immediately, or use attach_number later.3 params
Purchase a new phone number. Use area_code to request a specific region (e.g. '415' for San Francisco). Tip: pass agent_id to attach it immediately, or use attach_number later.
Parameters* required
agent_idstringAgent ID to attach this number to immediately
area_codestring3-digit area code for a specific region (e.g. '415', '212', '310')
countrystring2-letter ISO country code (e.g. US, CA, GB)default: US
send_messageSend an SMS or iMessage from one of your agent's phone numbers. USE THIS TOOL WHEN the user wants to text someone. The agent must have at least one phone number attached. If the agent has multiple numbers, use number_id to specify which one to send from.5 params
Send an SMS or iMessage from one of your agent's phone numbers. USE THIS TOOL WHEN the user wants to text someone. The agent must have at least one phone number attached. If the agent has multiple numbers, use number_id to specify which one to send from.
Parameters* required
agent_id*stringThe agent ID (must have a phone number attached — use list_agents to check)
body*stringThe message text to send
media_urlstringURL of an image or media file to attach (MMS)
number_idstringSpecific phone number ID to send from (if agent has multiple numbers)
to_number*stringRecipient phone number in E.164 format (e.g. +14155551234)
get_messagesGet SMS messages for a specific phone number. Use list_numbers to find the number ID. For threaded conversations, use list_conversations + get_conversation instead.2 params
Get SMS messages for a specific phone number. Use list_numbers to find the number ID. For threaded conversations, use list_conversations + get_conversation instead.
Parameters* required
limitnumberMax messages to returndefault: 50
number_id*stringThe ID of the phone number
list_callsList 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 IDs — use get_call with an ID to fetch the full transcript.7 params
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 IDs — use get_call with an ID to fetch the full transcript.
Parameters* required
agent_idstringFilter to calls for a specific agent
directionstringFilter by direction: 'inbound' or 'outbound'one of
inbound · outboundlimitnumberMax results to returndefault: 20
number_idstringFilter to calls for a specific phone number
offsetnumberNumber of results to skip (for pagination)default: 0
searchstringSearch by phone number or keyword
statusstringFilter by status: ringing, in-progress, completed, failed, busy, no-answer
get_callGet details and transcript for a specific call. Use list_calls to find call IDs. Pass wait=true to block until an in-progress call finishes before returning.3 params
Get details and transcript for a specific call. Use list_calls to find call IDs. Pass wait=true to block until an in-progress call finishes before returning.
Parameters* required
call_id*stringThe call ID
timeoutnumberMax seconds to wait when wait=true. Defaults to 120.default: 120
waitbooleanWhen true, long-polls until the call completes before returning. Useful for checking back on a call you initiated earlier.default: false
make_callInitiate an outbound phone call. USE THIS TOOL WHEN the user wants to place a webhook-driven call where your backend handles the conversation logic. DO NOT USE when the user wants an autonomous AI conversation — use make_conversation_call instead. The agent must have a phone n...5 params
Initiate an outbound phone call. USE THIS TOOL WHEN the user wants to place a webhook-driven call where your backend handles the conversation logic. DO NOT USE when the user wants an autonomous AI conversation — use make_conversation_call instead. The agent must have a phone n...
Parameters* required
agent_id*stringThe agent ID (must have a phone number attached — use list_agents to check)
from_number_idstringSpecific phone number ID to call from (if agent has multiple numbers)
initial_greetingstringWhat the agent says when the call connects
to_number*stringRecipient phone number in E.164 format (e.g. +14155551234)
voicestringVoice ID override for this call (use list_voices to see options)
make_conversation_callPlace a phone call where the AI has an autonomous conversation about a given topic. USE THIS TOOL WHEN the user wants an AI agent to call someone and have a conversation — scheduling, surveys, follow-ups, etc. No webhook setup needed. DO NOT USE when the user wants a webhook-d...8 params
Place a phone call where the AI has an autonomous conversation about a given topic. USE THIS TOOL WHEN the user wants an AI agent to call someone and have a conversation — scheduling, surveys, follow-ups, etc. No webhook setup needed. DO NOT USE when the user wants a webhook-d...
Parameters* required
agent_id*stringThe agent ID (must have a phone number attached)
from_number_idstringSpecific phone number ID to call from (if agent has multiple numbers)
initial_greetingstringWhat the AI says when the call connects. If not set, the AI will generate one from the topic.
max_wait_secondsnumberMaximum seconds to wait for the call to complete. Defaults to 300 (5 minutes).default: 300
to_number*stringRecipient phone number in E.164 format (e.g. +14155551234)
topic*stringThe conversation topic or instructions. This becomes the AI's system prompt. Be specific about what the AI should discuss, its personality, and any goals.
voicestringVoice ID override for this call (use list_voices to see options)
waitbooleanWhen true (default), blocks until the call ends and returns the full transcript.default: true
list_agentsList 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.1 params
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.
Parameters* required
limitnumberMax results to returndefault: 20
create_agentCreate a new agent. An agent owns phone numbers and handles calls/SMS. After creating, use buy_number or attach_number to give it a phone number. Set voice_mode to 'hosted' with a system_prompt for autonomous AI voice calls, or 'webhook' (default) to forward call transcripts t...9 params
Create a new agent. An agent owns phone numbers and handles calls/SMS. After creating, use buy_number or attach_number to give it a phone number. Set voice_mode to 'hosted' with a system_prompt for autonomous AI voice calls, or 'webhook' (default) to forward call transcripts t...
Parameters* required
begin_messagestringWhat the AI says when a call connects. Only used in 'hosted' mode.
descriptionstringDescription of what this agent does
model_tierstringModel quality/speed tier for hosted-mode agents. 'turbo' = fastest/cheapest, 'balanced' (default) = general use, 'max' = highest quality.one of
turbo · balanced · maxname*stringName for the agent (e.g. 'Customer Support', 'Sales Bot')
system_promptstringRequired when voice_mode is 'hosted'. The AI's personality and instructions for voice calls.
transfer_numberstringPhone number to transfer calls to (E.164 format). Enables call transfer during conversations.
voicestringVoice ID for the agent (use list_voices to see options). Defaults to 'Skylar - Friendly Guide'.
voice_modestring'webhook' (default) forwards transcripts to your webhook. 'hosted' uses built-in AI with system_prompt.one of
webhook · hostedvoicemail_messagestringVoicemail greeting text. When set, unanswered calls hear this message and can leave a voicemail.
update_agentUpdate an agent's configuration — name, description, voice settings, system prompt, greeting, call transfer, or voicemail. Only provided fields are updated. Use list_voices to see available voice IDs. Switching voice_mode to 'hosted' requires a system_prompt.10 params
Update an agent's configuration — name, description, voice settings, system prompt, greeting, call transfer, or voicemail. Only provided fields are updated. Use list_voices to see available voice IDs. Switching voice_mode to 'hosted' requires a system_prompt.
Parameters* required
agent_id*stringThe agent ID to update
begin_messagestringWhat the AI says when a call connects (hosted mode only).
descriptionstringNew description
model_tierstringModel quality/speed tier for hosted-mode agents. 'turbo' = fastest/cheapest, 'balanced' = general use, 'max' = highest quality.one of
turbo · balanced · maxnamestringNew name for the agent
system_promptstringThe AI's personality and instructions. Required when voice_mode is 'hosted'.
transfer_numberstringPhone number to transfer calls to (E.164 format), or empty string to remove.
voicestringVoice ID (use list_voices to see options).
voice_modestring'webhook' forwards transcripts to your webhook. 'hosted' uses built-in AI with system_prompt.one of
webhook · hostedvoicemail_messagestringVoicemail greeting text, or empty string to disable voicemail.
delete_agentDelete an agent permanently. Phone numbers attached to it will be kept but unassigned. DO NOT USE without confirming with the user — this cannot be undone.1 params
Delete an agent permanently. Phone numbers attached to it will be kept but unassigned. DO NOT USE without confirming with the user — this cannot be undone.
Parameters* required
agent_id*stringThe agent ID to delete
get_agentGet details for a specific agent including its phone numbers, voice configuration, and system prompt.1 params
Get details for a specific agent including its phone numbers, voice configuration, and system prompt.
Parameters* required
agent_id*stringThe agent ID
attach_numberAttach a phone number to an agent so the agent handles calls/SMS on that number. Use list_numbers to find unassigned number IDs and list_agents for agent IDs.2 params
Attach a phone number to an agent so the agent handles calls/SMS on that number. Use list_numbers to find unassigned number IDs and list_agents for agent IDs.
Parameters* required
agent_id*stringThe agent ID
number_id*stringThe phone number ID to attach
detach_numberDetach a phone number from an agent. The number is kept in your account but becomes unassigned. Use list_agents or get_agent to see which numbers are attached.2 params
Detach a phone number from an agent. The number is kept in your account but becomes unassigned. Use list_agents or get_agent to see which numbers are attached.
Parameters* required
agent_id*stringThe agent ID that currently owns the number
number_id*stringThe phone number ID to detach
list_voicesList available voices for agents. Use the voice_id value when calling create_agent or update_agent.
List available voices for agents. Use the voice_id value when calling create_agent or update_agent.
No parameters — call it with no arguments.
list_conversationsList 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. Use get_conversation with the ID to read messages.3 params
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. Use get_conversation with the ID to read messages.
Parameters* required
agent_idstringFilter to conversations for a specific agent
limitnumberMax results to returndefault: 20
offsetnumberNumber of results to skip (for pagination)default: 0
get_conversationGet a specific SMS conversation with message history. Use list_conversations to find IDs.2 params
Get a specific SMS conversation with message history. Use list_conversations to find IDs.
Parameters* required
conversation_id*stringThe conversation ID
message_limitnumberMax messages to includedefault: 50
update_conversationSet metadata on a conversation. Use this to store custom state, tags, or context that persists between messages. Pass null to clear metadata.2 params
Set metadata on a conversation. Use this to store custom state, tags, or context that persists between messages. Pass null to clear metadata.
Parameters* required
conversation_id*stringThe conversation ID
metadata*valueJSON metadata object to store on the conversation, or null to clear
get_usageGet account usage statistics. By default returns a summary with plan limits, quotas, and message/call volume. Use breakdown='daily' or 'monthly' for time-series data.3 params
Get account usage statistics. By default returns a summary with plan limits, quotas, and message/call volume. Use breakdown='daily' or 'monthly' for time-series data.
Parameters* required
breakdownstring'summary' for plan limits and totals, 'daily' for per-day breakdown, 'monthly' for per-month breakdownone of
summary · daily · monthlydefault: summarydaysnumberNumber of days to look back (only used with breakdown='daily')default: 30
monthsnumberNumber of months to look back (only used with breakdown='monthly')default: 12
get_webhookGet the webhook configuration. Pass agent_id to get an agent-specific webhook, or omit for the project-level default.1 params
Get the webhook configuration. Pass agent_id to get an agent-specific webhook, or omit for the project-level default.
Parameters* required
agent_idstringAgent ID to get that agent's webhook. Omit for project-level webhook.
set_webhookSet 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.4 params
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.
Parameters* required
agent_idstringAgent ID to set webhook for that agent only. Omit for project-level.
context_limitnumberNumber of recent messages to include as conversation context (0-50)
timeoutnumberWebhook response timeout in seconds
url*stringThe publicly accessible webhook URL (must be HTTPS in production)
delete_webhookRemove 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. DO NOT USE without confirming with the user.1 params
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. DO NOT USE without confirming with the user.
Parameters* required
agent_idstringAgent ID to delete that agent's webhook. Omit for project-level.
test_webhookSend 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.1 params
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.
Parameters* required
agent_idstringAgent ID to test that agent's webhook. Omit for project-level.
list_webhook_deliveriesView 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.3 params
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.
Parameters* required
agent_idstringAgent ID to see deliveries for that agent's webhook. Omit for project-level.
hoursnumberOnly show deliveries from the last N hours
limitnumberMax results to returndefault: 20
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:
AGENTPHONE_API_KEY=your_api_key npx agentphone-mcp --http --port 3000
Then connect to http://localhost:3000/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 is built on the mcp-use server framework,
which owns the HTTP layer: Streamable HTTP, the SSE stream, session management,
and the OAuth discovery endpoints. npm start (or the Docker image) runs it as
an HTTP server on PORT (default 3000), reachable at /mcp.
- Hosted:
https://mcp.agentphone.ai/mcp - Self-hosted:
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): set
AGENTPHONE_API_KEY. Used as the fallback credential when no OAuth token is present.
The per-request access token is forwarded to the AgentPhone REST API, so the server stores no credentials.
Environment
| Var | Purpose |
|---|---|
PORT | HTTP port (default 3000) |
AGENTPHONE_API_KEY | Fallback API key when OAuth is off |
MCP_OAUTH_CLIENT_ID | Enable OAuth; a gateway client pre-registered with the AgentPhone AS |
MCP_OAUTH_CLIENT_SECRET | Optional. Set = confidential gateway; unset = public client (gateway registered with token_endpoint_auth_method=none, advertises none downstream) |
AGENTPHONE_BASE_URL | API base (default https://api.agentphone.ai) |
AGENTPHONE_OAUTH_AUTHORIZE | Override authorize/consent URL (default https://agentphone.ai/oauth/authorize) |
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
All Tools (28)
Account
| Tool | Description |
|---|---|
account_overview | Get a full snapshot of your account — agents, numbers, webhook, and usage |
get_usage | Get usage stats — number usage, billed SMS segments, and message/call/webhook volume. Use breakdown for daily or monthly time-series. |
Phone Numbers
| Tool | Description |
|---|---|
list_numbers | List all phone numbers in your account |
buy_number | Purchase a new phone number with optional area_code and agent_id |
SMS
| Tool | Description |
|---|---|
send_message | Send SMS or iMessage. Supports media, threaded replies (reply_to_message_id), iMessage send effects (send_style), and group chats |
get_messages | Get messages for a specific number |
list_conversations | List SMS conversations. Pass agent_id to filter by agent. |
get_conversation | Get a conversation with full message history |
update_conversation | Set metadata on a conversation |
Contacts
| Tool | Description |
|---|---|
list_contacts | List saved contacts (address book). Filter with a search term. |
manage_contact | Create, update, or delete a contact (set action) |
Voice Calls
| Tool | Description |
|---|---|
list_calls | List calls. Filter by agent_id, number_id, status, direction, or keyword. |
get_call | Get call details and transcript |
make_call | Place an outbound call (webhook-driven) |
make_conversation_call | Place a call with built-in AI conversation — no webhook needed |
Agents
| Tool | Description |
|---|---|
list_agents | List all agents with their numbers and voice config |
create_agent | Create an agent with voice, system prompt, call transfer, voicemail, and voice tuning (speed, interruption sensitivity, backchannel, language, and more) |
update_agent | Update an agent's configuration |
delete_agent | Delete an agent (numbers are kept but unassigned) |
get_agent | Get agent details including phone numbers and voice config |
attach_number | Assign a phone number to an agent |
detach_number | Remove a phone number from an agent |
list_voices | 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 | Get webhook configuration |
set_webhook | Set a webhook URL for inbound messages and call events |
delete_webhook | Remove a webhook |
test_webhook | Send a test event to verify your webhook works |
list_webhook_deliveries | View delivery history for debugging |
Environment Variables
| Variable | Required | Description |
|---|---|---|
AGENTPHONE_API_KEY | stdio: yes, HTTP: no | Your AgentPhone API key (HTTP mode can use Authorization header instead) |
AGENTPHONE_BASE_URL | No | Override the API base URL (defaults to https://api.agentphone.ai) |
PORT | No | Port for HTTP mode (defaults to 3000, overridden by --port) |
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)
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 Network
Outbound: 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
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Configuration
AGENTPHONE_API_KEY*secretYour AgentPhone API key. Get one at https://agentphone.to
Registryactive
Packageagentphone-mcp
TransportSTDIO, HTTP
AuthRequired
Tools verifiedJun 11, 2026
UpdatedApr 24, 2026