{
  "markdown": "# AgentPhone MCP Server\n\nGive AI agents real phone numbers, SMS, and voice calls via the [Model Context Protocol](https://modelcontextprotocol.io).\n\n**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.\n\n**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.\n\n## Quick Start\n\n### 1. Get your API key\n\nSign up at [agentphone.ai](https://agentphone.ai) and create an API key from **Settings**.\n\n### 2. Connect via MCP\n\n**Option A: Remote server (recommended)**\n\nPoint your MCP client at the hosted endpoint — no install needed:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentphone\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://mcp.agentphone.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nWorks with any MCP client that supports Streamable HTTP transport (Switchboard, remote agent platforms, etc.).\n\n**Option B: Local server (stdio)**\n\nRuns locally via `npx` — works with Cursor, Claude Desktop, Windsurf, and Claude Code:\n\n**Cursor:** Settings > MCP or `~/.cursor/mcp.json`\n**Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"agentphone\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentphone-mcp\"],\n      \"env\": {\n        \"AGENTPHONE_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Option C: Self-hosted HTTP server**\n\nRun your own HTTP MCP endpoint:\n\n```bash\nAGENTPHONE_API_KEY=your_api_key npx agentphone-mcp --http --port 3000\n```\n\nThen connect to `http://localhost:3000/mcp`.\n\n## What Can It Do?\n\nOnce configured, just ask your AI agent things like:\n\n- *\"Buy me a phone number in the 415 area code\"*\n- *\"Create a support agent that greets callers and helps with billing\"*\n- *\"Call +14155551234 and have a conversation about scheduling a dentist appointment\"*\n- *\"Text +14155551234 saying 'Your appointment is confirmed for 3pm tomorrow'\"*\n- *\"Show me my recent calls and transcripts\"*\n- *\"List the available voices and switch my agent to a different one\"*\n- *\"Set up a webhook so I get notified when someone calls or texts my number\"*\n- *\"Show me this month's usage breakdown\"*\n\n## Transport & hosting\n\nThe server is built on the [mcp-use](https://docs.mcp-use.com) server framework,\nwhich owns the HTTP layer: Streamable HTTP, the SSE stream, session management,\nand the OAuth discovery endpoints. `npm start` (or the Docker image) runs it as\nan HTTP server on `PORT` (default 3000), reachable at `/mcp`.\n\n- **Hosted:** `https://mcp.agentphone.ai/mcp`\n- **Self-hosted:** `PORT=3000 npm start` → `http://localhost:3000/mcp`\n\n### Authentication\n\n1. **OAuth (recommended for end users):** the framework proxies an\n   Authorization Code + PKCE flow to the AgentPhone authorization server, so the\n   client opens a browser to sign in at agentphone.ai — no key to paste. Enable\n   it by setting `MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET` (a client\n   pre-registered with the AgentPhone AS).\n2. **API key (scripts / single-tenant):** set `AGENTPHONE_API_KEY`. Used as the\n   fallback credential when no OAuth token is present.\n\nThe per-request access token is forwarded to the AgentPhone REST API, so the\nserver stores no credentials.\n\n### Environment\n\n| Var | Purpose |\n|-----|---------|\n| `PORT` | HTTP port (default 3000) |\n| `AGENTPHONE_API_KEY` | Fallback API key when OAuth is off |\n| `MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET` | Enable OAuth; client pre-registered with the AgentPhone AS |\n| `AGENTPHONE_BASE_URL` | API base (default `https://api.agentphone.ai`) |\n| `AGENTPHONE_OAUTH_AUTHORIZE` | Override authorize/consent URL (default `https://agentphone.ai/oauth/authorize`) |\n\n## Highlights\n\n- **Phone numbers** — buy and manage numbers in any US/CA area code\n- **SMS** — send and receive text messages, view conversation threads\n- **Voice calls** — place outbound calls with built-in AI conversation (no webhook needed) or bring your own webhook\n- **Inbound handling** — set up webhooks to receive and respond to inbound calls and texts in real time\n- **Agents** — create agents with custom voices, system prompts, call transfer, and voicemail\n- **Usage & billing** — monitor number usage, message/call/webhook volume, and daily/monthly breakdowns\n\n## All Tools (28)\n\n### Account\n\n| Tool | Description |\n|------|-------------|\n| `account_overview` | Get a full snapshot of your account — agents, numbers, webhook, and usage |\n| `get_usage` | Get usage stats — number usage, billed SMS segments, and message/call/webhook volume. Use `breakdown` for daily or monthly time-series. |\n\n### Phone Numbers\n\n| Tool | Description |\n|------|-------------|\n| `list_numbers` | List all phone numbers in your account |\n| `buy_number` | Purchase a new phone number with optional `area_code` and `agent_id` |\n\n### SMS\n\n| Tool | Description |\n|------|-------------|\n| `send_message` | Send SMS or iMessage. Supports media, threaded replies (`reply_to_message_id`), iMessage send effects (`send_style`), and group chats |\n| `get_messages` | Get messages for a specific number |\n| `list_conversations` | List SMS conversations. Pass `agent_id` to filter by agent. |\n| `get_conversation` | Get a conversation with full message history |\n| `update_conversation` | Set metadata on a conversation |\n\n### Contacts\n\n| Tool | Description |\n|------|-------------|\n| `list_contacts` | List saved contacts (address book). Filter with a `search` term. |\n| `manage_contact` | Create, update, or delete a contact (set `action`) |\n\n### Voice Calls\n\n| Tool | Description |\n|------|-------------|\n| `list_calls` | List calls. Filter by `agent_id`, `number_id`, status, direction, or keyword. |\n| `get_call` | Get call details and transcript |\n| `make_call` | Place an outbound call (webhook-driven) |\n| `make_conversation_call` | Place a call with built-in AI conversation — no webhook needed |\n\n### Agents\n\n| Tool | Description |\n|------|-------------|\n| `list_agents` | List all agents with their numbers and voice config |\n| `create_agent` | Create an agent with voice, system prompt, call transfer, voicemail, and voice tuning (speed, interruption sensitivity, backchannel, language, and more) |\n| `update_agent` | Update an agent's configuration |\n| `delete_agent` | Delete an agent (numbers are kept but unassigned) |\n| `get_agent` | Get agent details including phone numbers and voice config |\n| `attach_number` | Assign a phone number to an agent |\n| `detach_number` | Remove a phone number from an agent |\n| `list_voices` | List available voices for agents |\n\n### Webhooks\n\nAll webhook tools accept an optional `agent_id` — pass it to manage an agent-specific webhook, omit it for the project-level default. Agent webhooks take priority over project-level.\n\n| Tool | Description |\n|------|-------------|\n| `get_webhook` | Get webhook configuration |\n| `set_webhook` | Set a webhook URL for inbound messages and call events |\n| `delete_webhook` | Remove a webhook |\n| `test_webhook` | Send a test event to verify your webhook works |\n| `list_webhook_deliveries` | View delivery history for debugging |\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `AGENTPHONE_API_KEY` | stdio: yes, HTTP: no | Your AgentPhone API key (HTTP mode can use Authorization header instead) |\n| `AGENTPHONE_BASE_URL` | No | Override the API base URL (defaults to `https://api.agentphone.ai`) |\n| `PORT` | No | Port for HTTP mode (defaults to `3000`, overridden by `--port`) |\n\n## Development\n\n```bash\ngit clone https://github.com/AgentPhone-AI/agentphone-mcp.git\ncd agentphone-mcp\nnpm install\nnpm run dev     # Run with tsx (hot reload)\nnpm run build   # Compile TypeScript\nnpm start       # Run compiled JS (stdio)\n```\n\n## How It Works\n\nThis MCP server connects your AI assistant to the [AgentPhone API](https://agentphone.ai). Your assistant talks to the MCP server, which calls the AgentPhone API, which talks to the phone network.\n\n```\nYour AI Assistant  <-->  agentphone-mcp  <-->  AgentPhone API  <-->  Phone Network\n```\n\n**Outbound**: your assistant places calls and sends texts through AgentPhone's API.\n\n**Inbound**: when someone calls or texts your number, AgentPhone sends a webhook event to your server — you can then respond programmatically or let your agent's built-in AI handle it.\n\n## License\n\nMIT\n",
  "bytes": 8746,
  "sha": "ad69391e2d7a72fc66d9434fdc25639131fa428e2430e1822b64524edf4e4442",
  "repo_slug": "agentphone-ai/agentphone-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agentphone_ai_agentphone_6bbb33c8/readme"
}