AgentPhone

AgentPhone MCP Server

Give AI agents real phone numbers, SMS, and voice calls via the Model Context Protocol.

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.

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.

Quick Start

1. Get your API key

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

2. Connect via MCP

Option A: Remote server (recommended)

Point your MCP client at the hosted endpoint — no install needed:

{

"mcpServers": { "agentphone": { "type": "streamable-http", "url": "https://mcp.agentphone.ai/mcp", "headers": { "Authorization": "Bearer your_api_key_here" } } } }

Works with any MCP client that supports Streamable HTTP transport (Switchboard, remote agent platforms, etc.).

Option B: Local server (stdio)

Runs locally via npx — works with Cursor, Claude Desktop, Windsurf, and Claude Code:

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)

{

"mcpServers": { "agentphone": { "command": "npx", "args": ["-y", "agentphone-mcp"], "env": { "AGENTPHONE_API_KEY": "your_api_key_here" } } } }

Option C: Self-hosted HTTP server

Run your own HTTP MCP endpoint:

PORT=3000 npx agentphone-mcp --http

Then connect to http://localhost:3000/mcp and configure your MCP client to send Authorization: Bearer with each request. A server-side AGENTPHONE_API_KEY alone does not authorize HTTP callers.

Warning: AGENTPHONE_ALLOW_ANONYMOUS=true opts into using the server's AGENTPHONE_API_KEY for requests with no Authorization header, only when OAuth is off. Anyone who can reach that endpoint can act as the account: only enable this behind your own authentication. Malformed headers are rejected, and a caller's supplied bearer is never replaced by the server key.

What Can It Do?

Once configured, just ask your AI agent things like:

• *"Buy me a phone number in the 415 area code"*
• *"Create a support agent that greets callers and helps with billing"*
• *"Call +14155551234 and have a conversation about scheduling a dentist appointment"*
• *"Text +14155551234 saying 'Your appointment is confirmed for 3pm tomorrow'"*
• *"Show me my recent calls and transcripts"*
• *"List the available voices and switch my agent to a different one"*
• *"Set up a webhook so I get notified when someone calls or texts my number"*
• *"Show me this month's usage breakdown"*

Transport & hosting

The server ships two transports from one entry point (node dist/index.js):

• stdio (default): bare npm start / npx agentphone-mcp runs the standard MCP stdio transport for local clients, using AGENTPHONE_API_KEY.
• HTTP: set PORT (or pass --http, optionally with --port ) to run the Streamable HTTP server, reachable at /mcp. --port alone does not switch transports — --http or PORT selects HTTP. The HTTP layer is built on the mcp-use framework, which owns Streamable HTTP, the SSE stream, session management, and the OAuth discovery endpoints.

• Hosted: https://mcp.agentphone.ai/mcp
• Self-hosted HTTP: PORT=3000 npm start → http://localhost:3000/mcp

Authentication

1. OAuth (recommended for end users): the framework proxies an Authorization Code + PKCE flow to the AgentPhone authorization server, so the client opens a browser to sign in at agentphone.ai — no key to paste. Enable it by setting MCP_OAUTH_CLIENT_ID (a client pre-registered with the AgentPhone AS). MCP_OAUTH_CLIENT_SECRET is optional: set it to run the gateway as a confidential client, or leave it unset to run as a public client (the gateway must then be registered with token_endpoint_auth_method=none). Public mode advertises none to downstream clients, which strict OAuth clients require.
2. API key (scripts / single-tenant, OAuth off): each request sends Authorization: Bearer . The server-side AGENTPHONE_API_KEY is only used for callers that send nothing, and only when AGENTPHONE_ALLOW_ANONYMOUS=true. Without that flag an unauthenticated call is rejected, so an exposed port cannot act as your account.

With OAuth enabled, bearer tokens are verified through the backend’s /auth/me; the anonymous opt-in does not bypass that verification.

The caller’s credential is forwarded to the AgentPhone REST API for validation. The optional anonymous mode instead uses the configured server API key.

Environment

Support matrix

Highlights

• Phone numbers — buy and manage numbers in any US/CA area code
• SMS — send and receive text messages, view conversation threads
• Voice calls — place outbound calls with built-in AI conversation (no webhook needed) or bring your own webhook
• Inbound handling — set up webhooks to receive and respond to inbound calls and texts in real time
• Agents — create agents with custom voices, system prompts, call transfer, and voicemail
• Usage & billing — monitor number usage, message/call/webhook volume, and daily/monthly breakdowns

Authorization & AI disclosure

• Every outbound call and message is individually authorized by the user. make_call, make_conversation_call, and send_message do nothing unless confirm=true is passed — without it they return a preview of the full destination(s) and content (all group recipients, the complete message body, every media URL, and any interactive payload) for the user to approve first (the same two-step pattern buy_number uses). There is no bulk-send path that skips a person in the loop.
• The connector adds AI self-identification to what it submits. Outbound calls placed through the call tools open with an AI disclosure that no argument disables. When a hosted agent is created or updated through this connector, the connector also prepends the disclosure to its system prompt, opening line, and voicemail so they identify as AI on inbound calls and voicemail. This is disclosure text and prompt instruction that the connector submits — it guides, but does not itself guarantee, model behavior or backend playback, and it only covers agents created/updated through this connector (the AgentPhone backend is the authoritative enforcer for all inbound calls). Webhook agents (your own backend, which may be human-staffed) are left untouched.
• No audio is exposed. Voice synthesis happens only inside live calls; no tool returns audio files or call recordings. (list_voices includes a static voice-sample preview_audio_url, which is a library clip, not call audio.)

All Tools (32)

Account

Phone Numbers

SMS

Contacts

Voice Calls

| make_conversation_call | Place a call with built-in AI conversation — no webhoo