MCP Server | AgentPhone

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.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:

“Buy me a US phone number”
“Show me my recent calls and transcripts”
“Call +14155551234 and have a conversation about scheduling a dentist appointment”
“Create an agent called Support Bot and give it a number”
“Show me the latest SMS messages”
“Set up a webhook to receive inbound messages”

Environment variables

Variable	Required	Description
`AGENTPHONE_API_KEY`	Yes	Your AgentPhone API key
`AGENTPHONE_BASE_URL`	No	Override the API base URL (defaults to production)

Available tools

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	`country` (2-letter ISO code, default: “US”), `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 conversations 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 (inbound and outbound)	`limit` (1-100, default: 20)
`get_call`	Get call details and transcript	`call_id`
`make_call`	Place an outbound call (uses your webhook for responses)	`agent_id`, `to_number` (E.164), `initial_greeting` (optional)
`make_conversation_call`	Place a call with a built-in AI conversation on a topic you define	`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.

Agents

Tool	Description	Parameters
`list_agents`	List all agents in your account	`limit` (1-100, default: 20)
`create_agent`	Create a new agent	`name`, `description` (optional)
`get_agent`	Get agent details and attached numbers	`agent_id`
`attach_number`	Assign a phone number to an agent	`agent_id`, `number_id`

Webhooks

Tool	Description	Parameters
`get_webhook`	Get the currently configured webhook endpoint	—
`set_webhook`	Set a webhook URL for inbound events	`url`, `context_limit` (0-50, optional)
`delete_webhook`	Remove the currently configured webhook	—

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.

$ npm install -g agentphone-mcp