> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://agentphone.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentphone.ai/docs/_mcp/server. # Connect Your AI Agent > Give any MCP-compatible AI agent a phone — calls, SMS, and iMessage through one config block 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](/mcp) that works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Claude Desktop, OpenClaw, Hermes, GBrain, and more. Quickstarts for each are below. The config block is the same everywhere — only where you put it changes. > **Tip** > > **Remote clients:** the server is also hosted at `https://mcp.agentphone.ai/mcp` (Streamable HTTP). Use it for Claude Code web, ChatGPT, cloud agent frameworks, or anywhere you can't run `npx`. Auth is browser sign-in or an `Authorization: Bearer YOUR_API_KEY` header. See the [MCP Server page](/mcp#hosted-server-streamable-http) for details. ## Claude Code ### Option A: Hosted MCP server (recommended) Connect to the hosted Streamable HTTP endpoint. Nothing to install, and it works in **Claude Code web** where local `npx` servers do not. ```bash claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp ``` Claude Code opens a browser window to sign in. To use an API key instead: ```bash claude mcp add --transport http agentphone https://mcp.agentphone.ai/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` ### Option B: Local MCP server (npm) ```bash claude mcp add agentphone -- npx -y agentphone-mcp ``` Then set your API key: ```bash export AGENTPHONE_API_KEY=your_api_key_here ``` ### Option C: Skill (slash command) ```bash npx skills add AgentPhone-AI/skills ``` ```bash 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 ``` > **Info** > > The MCP server exposes the full set of phone tools your agent can call autonomously. The [skill](/integrations/claude-code-skill) wraps the same tools behind a `/agentphone` command. Pick whichever style you prefer. ## Cursor Add to your Cursor MCP settings (`Settings > MCP` or `~/.cursor/mcp.json`): **`~/.cursor/mcp.json`** ```json title="~/.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: **`MCP config`** ```json title="MCP config" { "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` **`claude_desktop_config.json`** ```json title="claude_desktop_config.json" { "mcpServers": { "agentphone": { "command": "npx", "args": ["-y", "agentphone-mcp"], "env": { "AGENTPHONE_API_KEY": "your_api_key_here" } } } } ``` ## OpenClaw [OpenClaw](https://github.com/openclaw/openclaw) supports MCP servers natively. Add the block to your OpenClaw MCP configuration: **`MCP config`** ```json title="MCP config" { "mcpServers": { "agentphone": { "command": "npx", "args": ["-y", "agentphone-mcp"], "env": { "AGENTPHONE_API_KEY": "your_api_key_here" } } } } ``` > *"Buy me a US number and create a voice agent that answers calls as my personal assistant, then call +14155551234 to test it."* ## Hermes [Hermes](https://github.com/NousResearch/hermes-agent) reads MCP servers from its `config.yaml`: **`config.yaml`** ```yaml title="config.yaml" 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 [GBrain](https://github.com/garrytan/gbrain) is MCP-native — add AgentPhone alongside your brain so the agent has both context and a phone: **`MCP config`** ```json title="MCP config" { "mcpServers": { "gbrain": { "command": "npx", "args": ["-y", "gbrain-mcp"], "env": { "GBRAIN_DIR": "/path/to/your/brain" } }, "agentphone": { "command": "npx", "args": ["-y", "agentphone-mcp"], "env": { "AGENTPHONE_API_KEY": "your_api_key_here" } } } } ``` > *"Create a voice agent called Brain that greets callers warmly, buy it a 415 number, then call me at +14155551234."* ## Handling inbound calls & texts The MCP server is perfect for agent-initiated actions (buying numbers, making calls, sending texts). To have your agent **respond** to inbound calls and messages in real time, point an AgentPhone webhook at your server — every inbound message and call transcript is delivered as an event. See the [Webhooks](/documentation/guides/webhooks) guide. ## What your agent can do Once configured, your agent has the full AgentPhone toolset: | Category | Tools | Example prompt | | ------------------ | --------------------------------------- | ------------------------------------------------------------------------------ | | **Phone numbers** | Buy, list, release | *"Buy a US number with area code 212"* | | **Voice calls** | Make calls, list calls, get transcripts | *"Call +1234567890 and ask about their return policy"* | | **SMS & iMessage** | Send, read messages, list conversations | *"Show me texts from the 415 number"* | | **Agents** | Create, update, configure voice | *"Create a support agent with a friendly greeting"* | | **Contacts** | Save, look up, update | *"Save this number as Jane Doe"* | | **Webhooks** | Set up, manage per-agent routing | *"Set my webhook to [https://my-server.com/hook](https://my-server.com/hook)"* | ## 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](https://agentphone.ai) and grab your key from [Settings](https://agentphone.ai/settings). No Twilio account, no server, no ngrok needed.