> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentphone.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server. # MCP Server > Give AI agents phone numbers, SMS, and voice calls via the Model Context Protocol 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](https://img.shields.io/npm/v/agentphone-mcp)](https://www.npmjs.com/package/agentphone-mcp) ``` 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.ai](https://agentphone.ai) 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) ```json { "mcpServers": { "agentphone": { "command": "npx", "args": ["-y", "agentphone-mcp"], "env": { "AGENTPHONE_API_KEY": "your_api_key_here", "AGENTPHONE_BASE_URL": "https://api.agentphone.ai" } } } } ``` 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 ```bash 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`](https://www.npmjs.com/package/agentphone-mcp) on npm. ```bash npx -y agentphone-mcp ```