AgentPhone

agentphone-ai/agentphone-mcp

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.

GitHub stars: 125
tools: 26
auth: Secret needed
transport: STDIO, HTTP
env var: 1
last updated: Oct 21, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://mcp.agentphone.ai/mcp --name agentphone --header 'Authorization: Bearer ${API_TOKEN}'

Run in your terminal. add-mcp asks which agents to add it to, then asks for each value it needs. Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp --header 'Authorization: YOUR_AUTHORIZATION'

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 26 tools

Verified live against the running server on Jun 11, 2026.

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

limitnumber

Max results to returndefault: 20

offsetnumber

Number 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_idstring

Agent ID to attach this number to immediately

area_codestring

3-digit area code for a specific region (e.g. '415', '212', '310')

countrystring

2-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*string

The agent ID (must have a phone number attached — use list_agents to check)

body*string

The message text to send

media_urlstring

URL of an image or media file to attach (MMS)

number_idstring

Specific phone number ID to send from (if agent has multiple numbers)

to_number*string

Recipient 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

limitnumber

Max messages to returndefault: 50

number_id*string

The 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_idstring

Filter to calls for a specific agent

directionstring

Filter by direction: 'inbound' or 'outbound'one of inbound · outbound

limitnumber

Max results to returndefault: 20

number_idstring

Filter to calls for a specific phone number

offsetnumber

Number of results to skip (for pagination)default: 0

searchstring

Search by phone number or keyword

statusstring

Filter 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*string

The call ID

timeoutnumber

Max seconds to wait when wait=true. Defaults to 120.default: 120

waitboolean

When 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*string

The agent ID (must have a phone number attached — use list_agents to check)

from_number_idstring

Specific phone number ID to call from (if agent has multiple numbers)

initial_greetingstring

What the agent says when the call connects

to_number*string

Recipient phone number in E.164 format (e.g. +14155551234)

voicestring

Voice 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*string

The agent ID (must have a phone number attached)

from_number_idstring

Specific phone number ID to call from (if agent has multiple numbers)

initial_greetingstring

What the AI says when the call connects. If not set, the AI will generate one from the topic.

max_wait_secondsnumber

Maximum seconds to wait for the call to complete. Defaults to 300 (5 minutes).default: 300

to_number*string

Recipient phone number in E.164 format (e.g. +14155551234)

topic*string

The conversation topic or instructions. This becomes the AI's system prompt. Be specific about what the AI should discuss, its personality, and any goals.

voicestring

Voice ID override for this call (use list_voices to see options)

waitboolean

When 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

limitnumber

Max 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_messagestring

What the AI says when a call connects. Only used in 'hosted' mode.

descriptionstring

Description of what this agent does

model_tierstring

Model quality/speed tier for hosted-mode agents. 'turbo' = fastest/cheapest, 'balanced' (default) = general use, 'max' = highest quality.one of turbo · balanced · max

name*string

Name for the agent (e.g. 'Customer Support', 'Sales Bot')

system_promptstring

Required when voice_mode is 'hosted'. The AI's personality and instructions for voice calls.

transfer_numberstring

Phone number to transfer calls to (E.164 format). Enables call transfer during conversations.

voicestring

Voice 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 · hosted

voicemail_messagestring

Voicemail 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*string

The agent ID to update

begin_messagestring

What the AI says when a call connects (hosted mode only).

descriptionstring

New description

model_tierstring

Model quality/speed tier for hosted-mode agents. 'turbo' = fastest/cheapest, 'balanced' = general use, 'max' = highest quality.one of turbo · balanced · max

namestring

New name for the agent

system_promptstring

The AI's personality and instructions. Required when voice_mode is 'hosted'.

transfer_numberstring

Phone number to transfer calls to (E.164 format), or empty string to remove.

voicestring

Voice 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 · hosted

voicemail_messagestring

Voicemail 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*string

The 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*string

The 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*string

The agent ID

number_id*string

The 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*string

The agent ID that currently owns the number

number_id*string

The 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_idstring

Filter to conversations for a specific agent

limitnumber

Max results to returndefault: 20

offsetnumber

Number 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*string

The conversation ID

message_limitnumber

Max 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*string

The conversation ID

metadata*value

JSON 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: summary

daysnumber

Number of days to look back (only used with breakdown='daily')default: 30

monthsnumber

Number 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_idstring

Agent 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_idstring

Agent ID to set webhook for that agent only. Omit for project-level.

context_limitnumber

Number of recent messages to include as conversation context (0-50)

timeoutnumber

Webhook response timeout in seconds

url*string

The 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_idstring

Agent 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_idstring

Agent 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_idstring

Agent ID to see deliveries for that agent's webhook. Omit for project-level.

hoursnumber

Only show deliveries from the last N hours

limitnumber

Max results to returndefault: 20

Configuration

AGENTPHONE_API_KEY*secret

Your AgentPhone API key. Get one at https://agentphone.ai

Readme

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

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"
      }
    }
  }
}

View the full README on GitHub

Details

Repository: github.com/agentphone-ai/agentphone-mcp
Package: agentphone-mcp
Transport: STDIO, HTTP
Auth: Required
Registry: MCP registry, active
Tools verified: Jun 11, 2026