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.

There are two ways to connect:

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 command configures the Claude Code CLI. Hosted clients must add the URL through their own connector settings; they cannot run a local stdio process on your machine.

Cursor, Windsurf, and other JSON-configured clients

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

{
  "mcpServers": {
    "agentphone": {
      "url": "https://mcp.agentphone.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

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

Claude Desktop and ChatGPT

In a client that supports custom remote MCP connections, add https://mcp.agentphone.ai/mcp through its connector/app settings. Complete OAuth sign-in where supported; clients that accept headers can instead use Authorization: Bearer YOUR_API_KEY. Availability and menu names depend on the client, plan, and workspace policy. After connecting, verify that account_overview is available.

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)

{
  "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

Available tools

The published MCP interface is versioned independently from the REST API. The 0.8.0 source exposes these 28 tools; use your connected server’s tools/list response for its exact names, fields, and current availability.

buy_number needs confirm: true to complete a paid purchase. Review its confirmation response first. get_usage reports counts and limits, not the credit balance. Number release and dedicated per-agent webhook tools are not exposed in this version; use the dashboard or REST API for those operations.

make_conversation_call supplies a topic for built-in AI voice. make_call uses the agent/call voice configuration. A phone call needs an eligible attached number and calling access. Texting still needs the channel’s registration, subscription, and sending permissions.

Receiving messages and calls

Connecting MCP makes tools available to the assistant; it does not automatically wake that assistant when a text arrives. Use a webhook for an application that responds in real time, or read message history through MCP. Hosted voice can answer incoming calls without a separate webhook server; custom voice logic needs a synchronous voice webhook.

Troubleshooting

• No tools: restart/reconnect the client, verify its transport settings, and inspect its MCP logs. Local stdio needs Node and npx on the client process’s PATH.
• 401: check the API key or repeat OAuth sign-in. The MCP bearer token and webhook signing secret are different credentials.
• Tool works but send fails: inspect the returned error. MCP does not bypass SMS registration, iMessage limits, or billing.
• Unknown tool: refresh discovery; REST coverage and MCP tool coverage are different.

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