> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.ai/mcp/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_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 works in Claude Code web as well as the CLI. The stdio `npx` command below does not work in Claude Code web.

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

Claude Desktop: **Settings → Connectors → Add custom connector**, paste `https://mcp.agentphone.ai/mcp`, and sign in when prompted. ChatGPT: **Settings → Connectors → Create** with the same URL.

### 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](/integrations/google-adk) and [LangChain](/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 (26)

### Account

| Tool               | Description                                                                                                    | Parameters |
| ------------------ | -------------------------------------------------------------------------------------------------------------- | ---------- |
| `account_overview` | Get a full snapshot of your account — agents, numbers, webhook, and usage. Call this first to orient yourself. | —          |
| `get_usage`        | Get detailed usage stats: balance, number count, message/call volume, webhook delivery stats.                  | —          |

### Phone Numbers

| Tool             | Description                                      | Parameters                                                                                                  |
| ---------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `list_numbers`   | List all phone numbers in your account           | `limit` (1-100, default: 20)                                                                                |
| `buy_number`     | Purchase a new phone number in a specific region | `country` (2-letter ISO, default: "US"), `area_code` (3-digit, optional, e.g. "415"), `agent_id` (optional) |
| `release_number` | Release a phone number (irreversible)            | `number_id`                                                                                                 |

### SMS

| Tool                 | Description                                      | Parameters                                              |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| `get_messages`       | Get SMS messages for a phone number              | `number_id`, `limit` (1-200, default: 50)               |
| `list_conversations` | List SMS conversation threads across all numbers | `limit` (1-100, default: 20)                            |
| `get_conversation`   | Get a conversation with full message history     | `conversation_id`, `message_limit` (1-100, default: 50) |

### Voice Calls

| Tool                     | Description                                                 | Parameters                                                              |
| ------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| `list_calls`             | List recent calls across all numbers                        | `limit` (1-100, default: 20)                                            |
| `list_calls_for_number`  | List calls for a specific phone number                      | `number_id`, `limit` (1-100, default: 20)                               |
| `get_call`               | Get call details and transcript                             | `call_id`                                                               |
| `make_call`              | Place an outbound call (uses your webhook for conversation) | `agent_id`, `to_number` (E.164), `initial_greeting` (optional)          |
| `make_conversation_call` | Place a call with built-in AI — no webhook needed           | `agent_id`, `to_number` (E.164), `topic`, `initial_greeting` (optional) |

> **Note**
>
> `make_call` forwards speech to your webhook for processing. `make_conversation_call` uses a built-in LLM so the AI can hold a full conversation autonomously — no webhook setup needed. The agent must have a phone number attached for either tool.

### Agents

| Tool            | Description                                                    | Parameters                                                                                                                        |
| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `list_agents`   | List all agents with their numbers and voice config            | `limit` (1-100, default: 20)                                                                                                      |
| `create_agent`  | Create a new agent with optional voice configuration           | `name`, `description`, `voice_mode` ("webhook" or "hosted"), `system_prompt`, `begin_message`, `voice` (all optional except name) |
| `update_agent`  | Update an agent's name, voice mode, prompt, greeting, or voice | `agent_id`, `name`, `description`, `voice_mode`, `system_prompt`, `begin_message`, `voice` (all optional except agent\_id)        |
| `delete_agent`  | Delete an agent (numbers are kept but unassigned)              | `agent_id`                                                                                                                        |
| `get_agent`     | Get agent details including phone numbers and voice config     | `agent_id`                                                                                                                        |
| `attach_number` | Assign a phone number to an agent                              | `agent_id`, `number_id`                                                                                                           |
| `list_voices`   | List available voices for agents                               | —                                                                                                                                 |

> **Note**
>
> Set `voice_mode` to `"hosted"` with a `system_prompt` for autonomous AI voice calls. Set it to `"webhook"` (default) to forward call transcripts to your webhook URL. Use `list_voices` to see available voice IDs before creating or updating an agent.

### Webhooks (project-level)

| Tool             | Description                                            | Parameters                              |
| ---------------- | ------------------------------------------------------ | --------------------------------------- |
| `get_webhook`    | Get the project-level webhook configuration            | —                                       |
| `set_webhook`    | Set a webhook URL for inbound messages and call events | `url`, `context_limit` (0-50, optional) |
| `delete_webhook` | Remove the project-level webhook                       | —                                       |

### Webhooks (per-agent)

| Tool                   | Description                                                        | Parameters                                          |
| ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| `get_agent_webhook`    | Get the webhook for a specific agent                               | `agent_id`                                          |
| `set_agent_webhook`    | Set a webhook URL for a specific agent (overrides project default) | `agent_id`, `url`, `context_limit` (0-50, optional) |
| `delete_agent_webhook` | Remove an agent's webhook (falls back to project default)          | `agent_id`                                          |

> **Note**
>
> Per-agent webhooks let you route different agents to different backends. When an agent has its own webhook, its events go there instead of the project-level webhook. Removing an agent's webhook causes it to fall back to the project default.

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

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