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.

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

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.ai"
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

Variable	Required	Description
`AGENTPHONE_API_KEY`	Yes	Your AgentPhone API key
`AGENTPHONE_BASE_URL`	No	Override the API base URL (defaults to `https://api.agentphone.ai`)

Available tools (26)

Account

Tool	Description	Parameters
`account_overview`	Get a full snapshot of your account — agents, numbers, webhook, and usage. Call this first to orient yourself.	—
`get_usage`	Get detailed usage stats: balance, number count, message/call volume, webhook delivery stats.	—

Phone Numbers

Tool	Description	Parameters
`list_numbers`	List all phone numbers in your account	`limit` (1-100, default: 20)
`buy_number`	Purchase a new phone number in a specific region	`country` (2-letter ISO, default: “US”), `area_code` (3-digit, optional, e.g. “415”), `agent_id` (optional)
`release_number`	Release a phone number (irreversible)	`number_id`

SMS

Tool	Description	Parameters
`get_messages`	Get SMS messages for a phone number	`number_id`, `limit` (1-200, default: 50)
`list_conversations`	List SMS conversation threads across all numbers	`limit` (1-100, default: 20)
`get_conversation`	Get a conversation with full message history	`conversation_id`, `message_limit` (1-100, default: 50)

Voice Calls

Tool	Description	Parameters
`list_calls`	List recent calls across all numbers	`limit` (1-100, default: 20)
`list_calls_for_number`	List calls for a specific phone number	`number_id`, `limit` (1-100, default: 20)
`get_call`	Get call details and transcript	`call_id`
`make_call`	Place an outbound call (uses your webhook for conversation)	`agent_id`, `to_number` (E.164), `initial_greeting` (optional)
`make_conversation_call`	Place a call with built-in AI — no webhook needed	`agent_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

Tool	Description	Parameters
`list_agents`	List all agents with their numbers and voice config	`limit` (1-100, default: 20)
`create_agent`	Create a new agent with optional voice configuration	`name`, `description`, `voice_mode` (“webhook” or “hosted”), `system_prompt`, `begin_message`, `voice` (all optional except name)
`update_agent`	Update an agent’s name, voice mode, prompt, greeting, or voice	`agent_id`, `name`, `description`, `voice_mode`, `system_prompt`, `begin_message`, `voice` (all optional except agent_id)
`delete_agent`	Delete an agent (numbers are kept but unassigned)	`agent_id`
`get_agent`	Get agent details including phone numbers and voice config	`agent_id`
`attach_number`	Assign a phone number to an agent	`agent_id`, `number_id`
`list_voices`	List 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)

Tool	Description	Parameters
`get_webhook`	Get the project-level webhook configuration	—
`set_webhook`	Set a webhook URL for inbound messages and call events	`url`, `context_limit` (0-50, optional)
`delete_webhook`	Remove the project-level webhook	—

Webhooks (per-agent)

Tool	Description	Parameters
`get_agent_webhook`	Get the webhook for a specific agent	`agent_id`
`set_agent_webhook`	Set a webhook URL for a specific agent (overrides project default)	`agent_id`, `url`, `context_limit` (0-50, optional)
`delete_agent_webhook`	Remove 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

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