AgentPhone MCP server

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/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.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

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 MCPOAUTHCLIENTID / MCPOAUTHCLIENTSECRET (a client pre-registered with the AgentPhone AS).

1. OAuth (recommended for end users): the framework proxies an

fallback credential when no OAuth token is present.

1. API key (scripts / single-tenant): set AGENTPHONEAPIKEY. Used as the

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

Environment

Shortened. The full README is on GitHub.