MCP Server

MCP Server

The AgentPhone MCP Server lets your AI agent buy phone numbers, send/receive SMS, and place voice calls — all through natural language in Cursor, Claude Desktop, Windsurf, or any MCP-compatible client.

npm

Your AI Assistant  ⟷  agentphone-mcp (local)  ⟷  AgentPhone API  ⟷  Phone Network

The MCP server is a thin, stateless bridge that translates MCP tool calls into AgentPhone API requests. All state (numbers, calls, messages) lives on the AgentPhone platform.

Quick start

1. Get your API key

Sign up at agentphone.to and create an API key from Settings.

2. Add to your AI client

Add the following to your MCP configuration:

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)

1{
2  "mcpServers": {
3    "agentphone": {
4      "command": "npx",
5      "args": ["-y", "agentphone-mcp"],
6      "env": {
7        "AGENTPHONE_API_KEY": "your_api_key_here",
8        "AGENTPHONE_BASE_URL": "https://api.agentphone.to"
9      }
10    }
11  }
12}

You can also clone the repo and run the built server directly with node dist/index.js.

3. Start using it

Once configured, ask your AI agent things like:

  • “Show me an overview of my account”
  • “Buy me a phone number in the 415 area code”
  • “Create a support agent with a hosted AI voice that greets callers and helps with billing”
  • “Call +14155551234 and have a conversation about scheduling a dentist appointment”
  • “List the available voices and switch my agent to a different one”
  • “Show me my recent calls and transcripts”
  • “Set up a webhook to receive inbound messages”
  • “How many numbers can I still provision?”

Environment variables

VariableRequiredDescription
AGENTPHONE_API_KEYYesYour AgentPhone API key
AGENTPHONE_BASE_URLNoOverride the API base URL (defaults to https://api.agentphone.to)

Available tools (26)

Account

ToolDescriptionParameters
account_overviewGet a full snapshot of your account — agents, numbers, webhook, and usage. Call this first to orient yourself.—
get_usageGet detailed usage stats: plan limits, number quotas, message/call volume, webhook delivery stats.—

Phone Numbers

ToolDescriptionParameters
list_numbersList all phone numbers in your accountlimit (1-100, default: 20)
buy_numberPurchase a new phone number in a specific regioncountry (2-letter ISO, default: “US”), area_code (3-digit, optional, e.g. “415”), agent_id (optional)
release_numberRelease a phone number (irreversible)number_id

SMS

ToolDescriptionParameters
get_messagesGet SMS messages for a phone numbernumber_id, limit (1-200, default: 50)
list_conversationsList SMS conversation threads across all numberslimit (1-100, default: 20)
get_conversationGet a conversation with full message historyconversation_id, message_limit (1-100, default: 50)

Voice Calls

ToolDescriptionParameters
list_callsList recent calls across all numberslimit (1-100, default: 20)
list_calls_for_numberList calls for a specific phone numbernumber_id, limit (1-100, default: 20)
get_callGet call details and transcriptcall_id
make_callPlace an outbound call (uses your webhook for conversation)agent_id, to_number (E.164), initial_greeting (optional)
make_conversation_callPlace a call with built-in AI — no webhook neededagent_id, to_number (E.164), topic, initial_greeting (optional)

make_call forwards speech to your webhook for processing. make_conversation_call uses a built-in LLM so the AI can hold a full conversation autonomously — no webhook setup needed. The agent must have a phone number attached for either tool.

Agents

ToolDescriptionParameters
list_agentsList all agents with their numbers and voice configlimit (1-100, default: 20)
create_agentCreate a new agent with optional voice configurationname, description, voice_mode (“webhook” or “hosted”), system_prompt, begin_message, voice (all optional except name)
update_agentUpdate an agent’s name, voice mode, prompt, greeting, or voiceagent_id, name, description, voice_mode, system_prompt, begin_message, voice (all optional except agent_id)
delete_agentDelete an agent (numbers are kept but unassigned)agent_id
get_agentGet agent details including phone numbers and voice configagent_id
attach_numberAssign a phone number to an agentagent_id, number_id
list_voicesList available voices for agents—

Set voice_mode to "hosted" with a system_prompt for autonomous AI voice calls. Set it to "webhook" (default) to forward call transcripts to your webhook URL. Use list_voices to see available voice IDs before creating or updating an agent.

Webhooks (project-level)

ToolDescriptionParameters
get_webhookGet the project-level webhook configuration—
set_webhookSet a webhook URL for inbound messages and call eventsurl, context_limit (0-50, optional)
delete_webhookRemove the project-level webhook—

Webhooks (per-agent)

ToolDescriptionParameters
get_agent_webhookGet the webhook for a specific agentagent_id
set_agent_webhookSet a webhook URL for a specific agent (overrides project default)agent_id, url, context_limit (0-50, optional)
delete_agent_webhookRemove an agent’s webhook (falls back to project default)agent_id

Per-agent webhooks let you route different agents to different backends. When an agent has its own webhook, its events go there instead of the project-level webhook. Removing an agent’s webhook causes it to fall back to the project default.

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

npm

The package is published as agentphone-mcp on npm.

$npx -y agentphone-mcp