> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://agentphone.to/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentphone.to/docs/_mcp/server.

# MCP Server

> Give AI agents phone numbers, SMS, and voice calls via the Model Context Protocol. Hosted Streamable HTTP endpoint at https://mcp.agentphone.ai/mcp, or run locally with npx agentphone-mcp.

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](https://img.shields.io/npm/v/agentphone-mcp)](https://www.npmjs.com/package/agentphone-mcp)

There are two ways to connect:

|            | Hosted (Streamable HTTP)                                                            | Local (npm, stdio)                         |
| ---------- | ----------------------------------------------------------------------------------- | ------------------------------------------ |
| Endpoint   | `https://mcp.agentphone.ai/mcp`                                                     | `npx -y agentphone-mcp`                    |
| Works with | Any remote-capable MCP client, including Claude Code web, ChatGPT, and cloud agents | Desktop clients that spawn a local process |
| Auth       | Browser sign-in (OAuth) or `Authorization: Bearer <api key>` header                 | `AGENTPHONE_API_KEY` env var               |
| Install    | Nothing                                                                             | Node 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

```bash
# 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`:

**`~/.cursor/mcp.json`**

```json title="~/.cursor/mcp.json"
{
  "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](/docs/integrations/google-adk) and [LangChain](/docs/integrations/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](https://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)

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

| Variable              | Required | Description                                                         |
| --------------------- | -------- | ------------------------------------------------------------------- |
| `AGENTPHONE_API_KEY`  | Yes      | Your AgentPhone API key                                             |
| `AGENTPHONE_BASE_URL` | No       | Override the API base URL (defaults to `https://api.agentphone.ai`) |

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

| Category      | Tools                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Account       | `account_overview`, `get_usage`                                                                                             |
| Numbers       | `list_numbers`, `buy_number`                                                                                                |
| Messages      | `send_message`, `get_messages`                                                                                              |
| Calls         | `list_calls`, `get_call`, `make_call`, `make_conversation_call`                                                             |
| Agents        | `list_agents`, `create_agent`, `update_agent`, `delete_agent`, `get_agent`, `attach_number`, `detach_number`, `list_voices` |
| Conversations | `list_conversations`, `get_conversation`, `update_conversation`                                                             |
| Contacts      | `list_contacts`, `manage_contact`                                                                                           |
| Webhooks      | `get_webhook`, `set_webhook`, `delete_webhook`, `test_webhook`, `list_webhook_deliveries`                                   |

`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](/docs/documentation/guides/webhooks) 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](/docs/sms-registration), [iMessage limits](/docs/imessage), or [billing](/docs/usage).
* **Unknown tool:** refresh discovery; REST coverage and MCP tool coverage are different.

## Development

```bash
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`](https://www.npmjs.com/package/agentphone-mcp) on npm.

```bash
npx -y agentphone-mcp
```