Skip to content
Back to search

agentphone-mcp

Give AI agents real phone numbers, SMS, and voice calls via the Model Context Protocol.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/AgentPhone-AI/agentphone-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/AgentPhone-AI/agentphone-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentphone-ai--agentphone-mcp/badge.svg)](/listings/agentphone-ai--agentphone-mcp)

HTML

<a href="/listings/agentphone-ai--agentphone-mcp"><img src="/api/listings/agentphone-ai--agentphone-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Get your API key

Sign up at [agentphone.ai](https://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/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 289 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AgentPhone MCP Server
  2. Give AI agents real phone numbers, SMS, and voice calls via the [Model Context Protocol](https://modelcontextprotocol.io).
  3. **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.
  4. **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.
  5. ## Quick Start
  6. ### 1. Get your API key
  7. Sign up at [agentphone.ai](https://agentphone.ai) and create an API key from **Settings**.
  8. ### 2. Connect via MCP
  9. **Option A: Remote server (recommended)**
  10. Point your MCP client at the hosted endpoint — no install needed:
  11. ```json
  12. {
  13. "mcpServers": {
  14. "agentphone": {
  15. "type": "streamable-http",
  16. "url": "https://mcp.agentphone.ai/mcp",
  17. "headers": {
  18. "Authorization": "Bearer your_api_key_here"
  19. }
  20. }
  21. }
  22. }
  23. ```
  24. Works with any MCP client that supports Streamable HTTP transport (Switchboard, remote agent platforms, etc.).
  25. **Option B: Local server (stdio)**
  26. Runs locally via `npx` — works with Cursor, Claude Desktop, Windsurf, and Claude Code:
  27. **Cursor:** Settings > MCP or `~/.cursor/mcp.json`
  28. **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
  29. ```json
  30. {
  31. "mcpServers": {
  32. "agentphone": {
  33. "command": "npx",
  34. "args": ["-y", "agentphone-mcp"],
  35. "env": {
  36. "AGENTPHONE_API_KEY": "your_api_key_here"
  37. }
  38. }
  39. }
  40. }
  41. ```
  42. **Option C: Self-hosted HTTP server**
  43. Run your own HTTP MCP endpoint:
  44. ```bash
  45. PORT=3000 npx agentphone-mcp --http
  46. ```
  47. Then connect to `http://localhost:3000/mcp` and configure your MCP client to send
  48. `Authorization: Bearer <your AgentPhone API key>` with each request. A server-side
  49. `AGENTPHONE_API_KEY` alone does **not** authorize HTTP callers.
  50. **Warning:** `AGENTPHONE_ALLOW_ANONYMOUS=true` opts into using the server's
  51. `AGENTPHONE_API_KEY` for requests with no `Authorization` header, only when OAuth
  52. is off. Anyone who can reach that endpoint can act as the account: only enable
  53. this behind your own authentication. Malformed headers are rejected, and a
  54. caller's supplied bearer is never replaced by the server key.
  55. ## What Can It Do?
  56. Once configured, just ask your AI agent things like:
  57. - *"Buy me a phone number in the 415 area code"*
  58. - *"Create a support agent that greets callers and helps with billing"*
  59. - *"Call +14155551234 and have a conversation about scheduling a dentist appointment"*
  60. - *"Text +14155551234 saying 'Your appointment is confirmed for 3pm tomorrow'"*
  61. - *"Show me my recent calls and transcripts"*
  62. - *"List the available voices and switch my agent to a different one"*
  63. - *"Set up a webhook so I get notified when someone calls or texts my number"*
  64. - *"Show me this month's usage breakdown"*
  65. ## Transport & hosting
  66. The server ships two transports from one entry point (`node dist/index.js`):
  67. - **stdio** (default): bare `npm start` / `npx agentphone-mcp` runs the standard
  68. MCP stdio transport for local clients, using `AGENTPHONE_API_KEY`.
  69. - **HTTP**: set `PORT` (or pass `--http`, optionally with `--port <n>`) to run the
  70. Streamable HTTP server, reachable at `/mcp`. `--port` alone does not switch
  71. transports — `--http` or `PORT` selects HTTP. The HTTP layer is built on the
  72. [mcp-use](https://docs.mcp-use.com) framework, which owns Streamable HTTP, the
  73. SSE stream, session management, and the OAuth discovery endpoints.
  74. - **Hosted:** `https://mcp.agentphone.ai/mcp`
  75. - **Self-hosted HTTP:** `PORT=3000 npm start` → `http://localhost:3000/mcp`
  76. ### Authentication
  77. 1. **OAuth (recommended for end users):** the framework proxies an
  78. Authorization Code + PKCE flow to the AgentPhone authorization server, so the
  79. client opens a browser to sign in at agentphone.ai — no key to paste. Enable
  80. it by setting `MCP_OAUTH_CLIENT_ID` (a client pre-registered with the
  81. AgentPhone AS). `MCP_OAUTH_CLIENT_SECRET` is optional: set it to run the
  82. gateway as a confidential client, or leave it unset to run as a **public
  83. client** (the gateway must then be registered with
  84. `token_endpoint_auth_method=none`). Public mode advertises `none` to
  85. downstream clients, which strict OAuth clients require.
  86. 2. **API key (scripts / single-tenant, OAuth off):** each request sends
  87. `Authorization: Bearer <your API key>`. The server-side `AGENTPHONE_API_KEY` is
  88. only used for callers that send nothing, and only when
  89. `AGENTPHONE_ALLOW_ANONYMOUS=true`. Without that flag an unauthenticated call
  90. is rejected, so an exposed port cannot act as your account.
  91. With OAuth enabled, bearer tokens are verified through the backend’s `/auth/me`;
  92. the anonymous opt-in does not bypass that verification.
  93. The caller’s credential is forwarded to the AgentPhone REST API for validation.
  94. The optional anonymous mode instead uses the configured server API key.
  95. ### Environment
  96. | Var | Purpose |
  97. |-----|---------|
  98. | `PORT` | HTTP port (default 3000) |
  99. | `AGENTPHONE_API_KEY` | Fallback API key when OAuth is off. Only used for callers that send no `Authorization` header when `AGENTPHONE_ALLOW_ANONYMOUS=true` |
  100. | `AGENTPHONE_ALLOW_ANONYMOUS` | Default off; ignored when OAuth is enabled. Set to `true` to let requests with no `Authorization` header act with the server's `AGENTPHONE_API_KEY`. Anyone who can reach the port then controls the account: put the server behind your own auth first |
  101. | `MCP_OAUTH_CLIENT_ID` | Enable OAuth; a gateway client pre-registered with the AgentPhone AS |
  102. | `MCP_OAUTH_CLIENT_SECRET` | Optional. Set = confidential gateway; unset = public client (gateway registered with `token_endpoint_auth_method=none`, advertises `none` downstream) |
  103. | `AGENTPHONE_BASE_URL` | API base (default `https://api.agentphone.ai`) |
  104. | `AGENTPHONE_OAUTH_AUTHORIZE` | Override authorize/consent URL (default `https://agentphone.ai/oauth/authorize`) |
  105. | `AGENTPHONE_MCP_PUBLIC_URL` | Public base URL this server is reached at, advertised in the `/.well-known/mcp.json` install manifest (e.g. `https://mcp.agentphone.ai`). If unset, it's derived from the request. |
  106. | `WAKESHIFT_KEY` | Optional, HTTP only, with `AGENTPHONE_EVENTS_SECRET`. Turns on [Wakeshift](https://wakeshift.ai) wakes: adds `watch_messages`, which wakes the agent whenever a message arrives on any of the numbers it watches, and mentions it in the server instructions and in `send_message`'s result. Without both, the server runs exactly as before |
  107. | `AGENTPHONE_EVENTS_SECRET` | Optional, HTTP only, with `WAKESHIFT_KEY`. A Standard Webhooks secret (`whsec_…`) shared with the AgentPhone backend: turns on `POST /internal/events/message-received`, which the backend calls for each inbound message. See [docs/backend-events.md](docs/backend-events.md) |
  108. ## Support matrix
  109. | Dimension | Supported |
  110. |-----------|-----------|
  111. | Transports | stdio (default) and Streamable HTTP (set `PORT` / `--http`) |
  112. | Tested runtime | Node `^20.19.0 \|\| >=22.12.0` (CI runs 20, 22, 24) |
  113. | Clients | Any MCP client — verified with Cursor, Claude Desktop, Claude Code, Windsurf (stdio); Streamable-HTTP clients and remote agent platforms (HTTP) |
  114. | Auth modes | stdio: `AGENTPHONE_API_KEY`. HTTP: per-request bearer, OAuth (Authorization Code + PKCE), or anonymous server-key fallback (`AGENTPHONE_ALLOW_ANONYMOUS=true`, OAuth off) |
  115. | Channels | SMS and iMessage (send/receive); voice calls (webhook-driven or built-in AI) |
  116. | Number types | US and Canada numbers |
  117. ## Highlights
  118. - **Phone numbers** — buy and manage numbers in any US/CA area code
  119. - **SMS** — send and receive text messages, view conversation threads
  120. - **Voice calls** — place outbound calls with built-in AI conversation (no webhook needed) or bring your own webhook
  121. - **Inbound handling** — set up webhooks to receive and respond to inbound calls and texts in real time
  122. - **Agents** — create agents with custom voices, system prompts, call transfer, and voicemail
  123. - **Usage & billing** — monitor number usage, message/call/webhook volume, and daily/monthly breakdowns
  124. ## Authorization & AI disclosure
  125. - **Every outbound call and message is individually authorized by the user.** `make_call`, `make_conversation_call`, and `send_message` do nothing unless `confirm=true` is passed — without it they return a preview of the **full** destination(s) and content (all group recipients, the complete message body, every media URL, and any interactive payload) for the user to approve first (the same two-step pattern `buy_number` uses). There is no bulk-send path that skips a person in the loop.
  126. - **The connector adds AI self-identification to what it submits.** Outbound calls placed through the call tools open with an AI disclosure that no argument disables. When a **hosted** agent is created or updated through this connector, the connector also prepends the disclosure to its system prompt, opening line, and voicemail so they identify as AI on inbound calls and voicemail. This is disclosure text and prompt instruction that the connector submits — it guides, but does not itself guarantee, model behavior or backend playback, and it only covers agents created/updated through this connector (the AgentPhone backend is the authoritative enforcer for all inbound calls). Webhook agents (your own backend, which may be human-staffed) are left untouched.
  127. - **No audio is exposed.** Voice synthesis happens only inside live calls; no tool returns audio files or call recordings. (`list_voices` includes a static voice-sample `preview_audio_url`, which is a library clip, not call audio.)
  128. ## All Tools (32)
  129. ### Account
  130. | Tool | Description |
  131. |------|-------------|
  132. | `account_overview` | Get a full snapshot of your account — agents, numbers, webhook, and usage |
  133. | `get_usage` | Get usage stats — number usage, billed SMS segments, and message/call/webhook volume. Use `breakdown` for daily or monthly time-series. |
  134. ### Phone Numbers
  135. | Tool | Description |
  136. |------|-------------|
  137. | `list_numbers` | List all phone numbers in your account |
  138. | `buy_number` | Purchase a new phone number with optional `area_code` and `agent_id` |
  139. ### SMS
  140. | Tool | Description |
  141. |------|-------------|
  142. | `send_message` | Send SMS, iMessage, or WhatsApp. **Requires `confirm=true`** (previews first — every message is individually authorized by the user). Supports media, threaded replies (`reply_to_message_id`), iMessage effects (`send_style`), existing groups (`to_number`) or new groups (`recipients`), and WhatsApp interactive content (`channel=whatsapp` with `buttons`/`list`/`cta`/`template`) |
  143. | `check_capabilities` | Check which channels a phone number can receive (iMessage / SMS / RCS) before sending |
  144. | `check_readiness` | Check a number is ready before sending/calling: active + assigned + channel-capable are hard blockers; A2P/10DLC registration and recipient reachability are warnings. Returns `ready`, blockers, warnings, and next steps (credit/concurrency are enforced at send time, not pre-checkable) |
  145. | `get_messages` | Get messages for a specific number. Page older history with `cursor` (from `nextCursor`); `before`/`after` are optional time filters. |
  146. | `list_conversations` | List SMS conversations. Pass `agent_id` to filter by agent. |
  147. | `get_conversation` | Get a conversation with a bounded tail of recent messages |
  148. | `get_conversation_messages` | Page through a conversation's full message history with `cursor` |
  149. | `update_conversation` | Set metadata on a conversation |
  150. ### Contacts
  151. | Tool | Description |
  152. |------|-------------|
  153. | `list_contacts` | List saved contacts (address book). Filter with a `search` term. |
  154. | `manage_contact` | Create, update, or delete a contact (set `action`). Delete **requires `confirm=true`** (previews first; cannot be undone) |
  155. ### Voice Calls
  156. | Tool | Description |
  157. |------|-------------|
  158. | `list_calls` | List calls. Scope by `agent_id` **or** `number_id`, or filter the account-wide list by status/direction/search. Scope and filters can't be combined. |
  159. | `get_call` | Get call details and transcript, including end reason, failure reason when available, and whether a recording is available (the recording audio/link is never exposed) |
  160. | `end_call` | End an in-progress call (safe to retry; ending a finished call is a no-op) |
  161. | `make_call` | Place an outbound call (webhook-driven). **Requires `confirm=true`** (previews first — every call is individually authorized by the user). Supports recording, variables, model tier, call-screening controls, and `wait_for_speaker` (connect silently and let the person speak first) |
  162. | `make_conversation_call` | Place a call with built-in AI conversation — no webhook needed. **Requires `confirm=true`** (previews first — every call is individually authorized by the user). Supports recording, variables, model tier, call-screening controls, and `wait_for_speaker` |
  163. ### Agents
  164. | Tool | Description |
  165. |------|-------------|
  166. | `list_agents` | List all agents with their numbers and voice config |
  167. | `create_agent` | Create an agent with voice, system prompt, call transfer, voicemail, call-screening identity/purpose, and voice tuning (speed, interruption sensitivity, backchannel, language, and more) |
  168. | `update_agent` | Update an agent's configuration (incl. call-screening identity/purpose) |
  169. | `delete_agent` | Delete an agent (numbers are kept but unassigned) |
  170. | `get_agent` | Get agent details including phone numbers and voice config |
  171. | `attach_number` | Assign a phone number to an agent |
  172. | `detach_number` | Remove a phone number from an agent |
  173. | `list_voices` | List available voices for agents |
  174. ### Webhooks
  175. All webhook tools accept an optional `agent_id` — pass it to manage an agent-specific webhook, omit it for the project-level default. Agent webhooks take priority over project-level.
  176. | Tool | Description |
  177. |------|-------------|
  178. | `get_webhook` | Get webhook configuration |
  179. | `set_webhook` | Set a webhook URL for inbound messages and call events |
  180. | `delete_webhook` | Remove a webhook |
  181. | `test_webhook` | Send a test event to verify your webhook works |
  182. | `list_webhook_deliveries` | View delivery history for debugging |
  183. `get_webhook` and `set_webhook` never return the signing secret, for either scope —
  184. it is always masked, so it can't land in model context, transcripts, or client logs.
  185. Retrieve the secret from the AgentPhone dashboard to verify webhook signatures.
  186. ## Environment Variables
  187. | Variable | Required | Description |
  188. |----------|----------|-------------|
  189. | `AGENTPHONE_API_KEY` | stdio: yes; HTTP anonymous mode: yes | In HTTP mode, used only with `AGENTPHONE_ALLOW_ANONYMOUS=true`, OAuth off, and no caller Authorization header |
  190. | `AGENTPHONE_ALLOW_ANONYMOUS` | No | Explicit HTTP server-key fallback; default off, ignored when OAuth is enabled. See the self-hosting warning above |
  191. | `AGENTPHONE_BASE_URL` | No | Override the API base URL (defaults to `https://api.agentphone.ai`) |
  192. | `PORT` | No | Port for HTTP mode (defaults to `3000`; set with `PORT`) |
  193. | `WAKESHIFT_KEY` | No | HTTP only, with `AGENTPHONE_EVENTS_SECRET`. Wakeshift app key; adds `watch_messages` and points agents to it from the server instructions and `send_message`'s result. Without both, nothing is sent to Wakeshift |
  194. | `AGENTPHONE_EVENTS_SECRET` | No | HTTP only, with `WAKESHIFT_KEY`. Signing secret for backend message notifications; see [docs/backend-events.md](docs/backend-events.md) |
  195. ## Development
  196. ```bash
  197. git clone https://github.com/AgentPhone-AI/agentphone-mcp.git
  198. cd agentphone-mcp
  199. npm install
  200. npm run dev # Run with tsx (hot reload)
  201. npm run build # Compile TypeScript
  202. npm start # Run compiled JS — stdio by default; set PORT (or pass --http) for the HTTP server
  203. npm test # Build + run the full test suite (both transports, output-schema contracts)
  204. ```
  205. ### Release & deployment checks
  206. | Command | What it verifies |
  207. |---------|------------------|
  208. | `npm run check:release` | Version is identical across `package.json`, `server.json`, and the built handshake (run in `prepublishOnly`). |
  209. | `npm run smoke:pack` | Runs `npm pack`, installs the resulting tarball in a clean dir, and runs the 204 detach regression against that **packed tarball** (the same bytes `npm publish` would upload; run in `prepublishOnly`). |
  210. | `npm run check:contract` | Fetches the live OpenAPI and asserts the endpoints/fields the tools depend on still exist (message cursors + item fields, call filters, outbound-call request/response fields the client uses, the detach endpoint, and the `from_` sender field). Network-dependent, so it's not part of `npm test` — run before a release or as a non-blocking CI job. Override with `OPENAPI_URL`. |
  211. | `npm run canary` | Read-only post-deploy canary: connects to `MCP_CANARY_URL`, checks the handshake and tool surface, and (with `MCP_CANARY_TOKEN`) runs one read-only tool. No mutations; skips cleanly when `MCP_CANARY_URL` is unset. |
  212. ## How It Works
  213. This MCP server connects your AI assistant to the [AgentPhone API](https://agentphone.ai). Your assistant talks to the MCP server, which calls the AgentPhone API, which talks to the phone network.
  214. ```
  215. Your AI Assistant <--> agentphone-mcp <--> AgentPhone API <--> Phone Network
  216. ```
  217. **Outbound**: your assistant places calls and sends texts through AgentPhone's API.
  218. **Inbound**: when someone calls or texts your number, AgentPhone sends a webhook event to your server — you can then respond programmatically or let your agent's built-in AI handle it.
  219. ## License
  220. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.