MCP Server

The AgentPhone MCP Server lets your AI agent buy phone numbers, send/receive SMS, and place voice calls — all through natural language in Claude Code, Cursor, Claude Desktop, Windsurf, or any MCP-compatible client.

npm

There are two ways to connect:

Hosted (Streamable HTTP)Local (npm, stdio)
Endpointhttps://mcp.agentphone.ai/mcpnpx -y agentphone-mcp
Works withAny remote-capable MCP client, including Claude Code web, ChatGPT, and cloud agentsDesktop clients that spawn a local process
AuthBrowser sign-in (OAuth) or Authorization: Bearer <api key> headerAGENTPHONE_API_KEY env var
InstallNothingNode 18+
Your AI Assistant  ⟷  mcp.agentphone.ai/mcp  (or agentphone-mcp locally)  ⟷  AgentPhone API  ⟷  Phone Network

Either way, 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.

Hosted server (Streamable HTTP)

The hosted endpoint is the fastest way to connect, and the only option for clients that cannot spawn a local process (Claude Code web, ChatGPT, hosted agent frameworks).

https://mcp.agentphone.ai/mcp

Authentication

The endpoint accepts two forms of auth:

  • Browser sign-in (OAuth). Add the URL with no credentials. Clients that support MCP OAuth open a browser window to sign in; no key to paste.
  • API key. Send your key as a bearer token: Authorization: Bearer YOUR_API_KEY. Use this for clients without OAuth support, headless environments, and server-side frameworks.

An unauthenticated request returns 401 with {"error": "Missing Authorization header"}.

Claude Code

$# Browser sign-in
$claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp
$
$# Or with an API key
$claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp \
>  --header "Authorization: Bearer YOUR_API_KEY"

This works in Claude Code web as well as the CLI. The stdio npx command below does not work in Claude Code web.

Cursor, Windsurf, and other JSON-configured clients

Most clients accept a remote server in their mcpServers config. Cursor uses url:

~/.cursor/mcp.json
1{
2  "mcpServers": {
3    "agentphone": {
4      "url": "https://mcp.agentphone.ai/mcp",
5      "headers": {
6        "Authorization": "Bearer YOUR_API_KEY"
7      }
8    }
9  }
10}

Windsurf uses serverUrl instead of url. Drop the headers block to use browser sign-in where the client supports it.

Claude Desktop and ChatGPT

Claude Desktop: Settings → Connectors → Add custom connector, paste https://mcp.agentphone.ai/mcp, and sign in when prompted. ChatGPT: Settings → Connectors → Create with the same URL.

Python / server-side frameworks

Frameworks such as Google ADK, LangChain, and the OpenAI Agents SDK connect to the hosted URL directly with the bearer header. See the Google ADK and LangChain guides for full examples.

Local server (npm)

Run the same server as a local process when you prefer to keep the API key in your own environment.

1. Get your API key

Sign up at 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)

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

  • “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

VariableRequiredDescription
AGENTPHONE_API_KEYYesYour AgentPhone API key
AGENTPHONE_BASE_URLNoOverride the API base URL (defaults to https://api.agentphone.ai)

Available tools (26)

Account

ToolDescriptionParameters
account_overviewGet a full snapshot of your account — agents, numbers, webhook, and usage. Call this first to orient yourself.—
get_usageGet detailed usage stats: balance, number count, message/call volume, webhook delivery stats.—

Phone Numbers

ToolDescriptionParameters
list_numbersList all phone numbers in your accountlimit (1-100, default: 20)
buy_numberPurchase a new phone number in a specific regioncountry (2-letter ISO, default: “US”), area_code (3-digit, optional, e.g. “415”), agent_id (optional)
release_numberRelease a phone number (irreversible)number_id

SMS

ToolDescriptionParameters
get_messagesGet SMS messages for a phone numbernumber_id, limit (1-200, default: 50)
list_conversationsList SMS conversation threads across all numberslimit (1-100, default: 20)
get_conversationGet a conversation with full message historyconversation_id, message_limit (1-100, default: 50)

Voice Calls

ToolDescriptionParameters
list_callsList recent calls across all numberslimit (1-100, default: 20)
list_calls_for_numberList calls for a specific phone numbernumber_id, limit (1-100, default: 20)
get_callGet call details and transcriptcall_id
make_callPlace an outbound call (uses your webhook for conversation)agent_id, to_number (E.164), initial_greeting (optional)
make_conversation_callPlace a call with built-in AI — no webhook neededagent_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

ToolDescriptionParameters
list_agentsList all agents with their numbers and voice configlimit (1-100, default: 20)
create_agentCreate a new agent with optional voice configurationname, description, voice_mode (“webhook” or “hosted”), system_prompt, begin_message, voice (all optional except name)
update_agentUpdate an agent’s name, voice mode, prompt, greeting, or voiceagent_id, name, description, voice_mode, system_prompt, begin_message, voice (all optional except agent_id)
delete_agentDelete an agent (numbers are kept but unassigned)agent_id
get_agentGet agent details including phone numbers and voice configagent_id
attach_numberAssign a phone number to an agentagent_id, number_id
list_voicesList 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)

ToolDescriptionParameters
get_webhookGet the project-level webhook configuration—
set_webhookSet a webhook URL for inbound messages and call eventsurl, context_limit (0-50, optional)
delete_webhookRemove the project-level webhook—

Webhooks (per-agent)

ToolDescriptionParameters
get_agent_webhookGet the webhook for a specific agentagent_id
set_agent_webhookSet a webhook URL for a specific agent (overrides project default)agent_id, url, context_limit (0-50, optional)
delete_agent_webhookRemove 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

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

$npx -y agentphone-mcp