Connect Your AI Agent

Add phone calls, SMS, and iMessage to your AI agent. One config block and your agent can buy numbers, make calls, read texts, and manage voice agents — all through natural language.

AgentPhone ships an MCP server that works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Claude Desktop, OpenClaw, Hermes, GBrain, and more. Quickstarts for each are below. Configuration formats differ between clients. Use the matching example below and verify that the client discovers account_overview before trying paid actions.

Claude Code

Option A: Hosted MCP server (recommended)

Connect the Claude Code CLI to the hosted Streamable HTTP endpoint. For a hosted client, add the same URL through that client’s connector settings.

claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp

Use /mcp in Claude Code to authenticate the server when prompted. To use an API key instead:

claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Option B: Local MCP server (npm)

claude mcp add agentphone -- npx -y agentphone-mcp

Then set your API key:

export AGENTPHONE_API_KEY=your_api_key_here

Option C: Skill (slash command)

npx skills add AgentPhone-AI/skills

export AGENTPHONE_API_KEY=your_api_key_here

Then use /agentphone in any conversation:

/agentphone buy a 415 number and create a support agent
/agentphone call +14155551234 and ask about their hours
/agentphone show me my recent SMS conversations

Cursor

Add to your Cursor MCP settings (Settings > MCP or ~/.cursor/mcp.json):

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

Restart Cursor. In Composer or Chat, try:

“Create an agent and buy it a phone number, then call me at +14155551234 to test it.”

Windsurf

Add the same block to your Windsurf MCP configuration:

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

Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

OpenClaw

Open Settings → MCP in the Control UI, add a Streamable HTTP server named agentphone, and set the URL to https://mcp.agentphone.ai/mcp. Configure OAuth or the bearer header using the scoped settings editor, then probe the connection:

openclaw mcp doctor agentphone --probe

OpenClaw stores server definitions under mcp.servers, not a top-level mcpServers block. Follow the OpenClaw MCP guide for the format supported by your installed version.

Hermes

Hermes reads MCP servers from ~/.hermes/config.yaml under mcp_servers:

mcp_servers:
  agentphone:
    command: npx
    args: ["-y", "agentphone-mcp"]
    env:
      AGENTPHONE_API_KEY: your_api_key_here

Restart Hermes, then:

“Buy a number and create a voice agent, then call +14155551234 and schedule a dentist appointment for Thursday.”

GBrain

To use AgentPhone alongside GBrain, add both services to the MCP client hosting your agent. Use that client’s configuration format and GBrain’s own installation instructions. AgentPhone’s hosted URL and local stdio configuration are described above; there is no universal configuration file shared by all MCP applications.

Handling inbound calls & texts

The MCP server is perfect for agent-initiated actions (buying numbers, making calls, sending texts). For text responses and custom voice logic, point an AgentPhone webhook at your server. An MCP connection alone does not wake the assistant for incoming texts. Hosted voice can answer calls from its configured prompt without a separate server. See the Webhooks guide.

What your agent can do

Once configured, your agent has the full AgentPhone toolset:

Real-world examples

Customer research from your IDE

> Create an agent, buy it a number, then call these 5 restaurants
  and ask if they have availability for 8 people this Saturday:
  +14155551111, +14155552222, +14155553333, +14155554444, +14155555555
  Summarize what you find.

Test your app’s phone integration

> I just deployed a new IVR. Call +14155559999 and navigate through
  the menu — press 1 for sales, then ask about enterprise pricing.
  Tell me if anything sounds broken.

Set up a phone agent for your project

> Read my project's README and create a voice agent that can answer
  questions about this codebase. Give it a phone number and set the
  greeting to "Hi, I'm the docs bot for [project name]."

Get your API key

Sign up at agentphone.ai and grab your key from Settings. Hosted voice and agent-initiated MCP actions do not require your own webhook server. Real-time custom text responses do.