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

AGENTPHONE_API_KEY=your_api_key npx agentphone-mcp --http --port 3000

Then connect to http://localhost:3000/mcp.

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 is built on the mcp-use server framework, which owns the HTTP layer: Streamable HTTP, the SSE stream, session management, and the OAuth discovery endpoints. npm start (or the Docker image) runs it as an HTTP server on PORT (default 3000), reachable at /mcp.

• Hosted: https://mcp.agentphone.ai/mcp
• Self-hosted: 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 / MCP_OAUTH_CLIENT_SECRET (a client pre-registered with the AgentPhone AS).
2. API key (scripts / single-tenant): set AGENTPHONE_API_KEY. Used as the fallback credential when no OAuth token is present.

The per-request access token is forwarded to the AgentPhone REST API, so the server stores no credentials.

Environment

Var	Purpose
PORT	HTTP port (default 3000)
AGENTPHONE_API_KEY	Fallback API key when OAuth is off
MCP_OAUTH_CLIENT_ID / MCP_OAUTH_CLIENT_SECRET	Enable OAuth; client pre-registered with the AgentPhone AS
AGENTPHONE_BASE_URL	API base (default https://api.agentphone.ai)
AGENTPHONE_OAUTH_AUTHORIZE	Override authorize/consent URL (default https://agentphone.ai/oauth/authorize)

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 your plan limits, message/call volume, and daily/monthly breakdowns

All Tools (28)

Account

Tool	Description
account_overview	Get a full snapshot of your account — agents, numbers, webhook, and usage
get_usage	Get usage stats, plan limits, and quotas. Use breakdown for daily or monthly time-series.

Phone Numbers

Tool	Description
list_numbers	List all phone numbers in your account
buy_number	Purchase a new phone number with optional area_code and agent_id

SMS

Tool	Description
send_message	Send SMS or iMessage. Supports media, threaded replies (reply_to_message_id), iMessage send effects (send_style), and group chats
get_messages	Get messages for a specific number
list_conversations	List SMS conversations. Pass agent_id to filter by agent.
get_conversation	Get a conversation with full message history
update_conversation	Set metadata on a conversation

Contacts

Tool	Description
list_contacts	List saved contacts (address book). Filter with a search term.
manage_contact	Create, update, or delete a contact (set action)

Voice Calls

Tool	Description
list_calls	List calls. Filter by agent_id, number_id, status, direction, or keyword.
get_call	Get call details and transcript
make_call	Place an outbound call (webhook-driven)
make_conversation_call	Place a call with built-in AI conversation — no webhook needed

Agents

Tool	Description
list_agents	List all agents with their numbers and voice config
create_agent	Create an agent with voice, system prompt, call transfer, voicemail, and voice tuning (speed, interruption sensitivity, backchannel, language, and more)
update_agent	Update an agent's configuration
delete_agent	Delete an agent (numbers are kept but unassigned)
get_agent	Get agent details including phone numbers and voice config
attach_number	Assign a phone number to an agent
detach_number	Remove a phone number from an agent
list_voices	List available voices for agents

Webhooks

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

Tool	Description
get_webhook	Get webhook configuration
set_webhook	Set a webhook URL for inbound messages and call events
delete_webhook	Remove a webhook
test_webhook	Send a test event to verify your webhook works
list_webhook_deliveries	View delivery history for debugging

Environment Variables

Variable	Required	Description
AGENTPHONE_API_KEY	stdio: yes, HTTP: no	Your AgentPhone API key (HTTP mode can use Authorization header instead)
AGENTPHONE_BASE_URL	No	Override the API base URL (defaults to https://api.agentphone.ai)
PORT	No	Port for HTTP mode (defaults to 3000, overridden by --port)

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 (stdio)

How It Works

This MCP server connects your AI assistant to the AgentPhone API. Your assistant talks to the MCP server, which calls the AgentPhone API, which talks to the phone network.

Your AI Assistant  <-->  agentphone-mcp  <-->  AgentPhone API  <-->  Phone Network

Outbound: your assistant places calls and sends texts through AgentPhone's API.

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.

License

MIT