Skip to main content
Glama
AgentPhone MCP Server

AgentPhone MCP Server

Official

AgentPhone MCP Server

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

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.

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.

Quick Start

1. Get your API key

Sign up at 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:

PORT=3000 npx agentphone-mcp --http

Then connect to http://localhost:3000/mcp and configure your MCP client to send Authorization: Bearer <your AgentPhone API key> with each request. A server-side AGENTPHONE_API_KEY alone does not authorize HTTP callers.

Warning: AGENTPHONE_ALLOW_ANONYMOUS=true opts into using the server's AGENTPHONE_API_KEY for requests with no Authorization header, only when OAuth is off. Anyone who can reach that endpoint can act as the account: only enable this behind your own authentication. Malformed headers are rejected, and a caller's supplied bearer is never replaced by the server key.

Related MCP server: agentline-mcp

What Can It Do?

Once configured, just ask your AI agent things like:

  • "Buy me a phone number in the 415 area code"

  • "Create a support agent that greets callers and helps with billing"

  • "Call +14155551234 and have a conversation about scheduling a dentist appointment"

  • "Text +14155551234 saying 'Your appointment is confirmed for 3pm tomorrow'"

  • "Show me my recent calls and transcripts"

  • "List the available voices and switch my agent to a different one"

  • "Set up a webhook so I get notified when someone calls or texts my number"

  • "Show me this month's usage breakdown"

Transport & hosting

The server ships two transports from one entry point (node dist/index.js):

  • stdio (default): bare npm start / npx agentphone-mcp runs the standard MCP stdio transport for local clients, using AGENTPHONE_API_KEY.

  • HTTP: set PORT (or pass --http, optionally with --port <n>) to run the Streamable HTTP server, reachable at /mcp. --port alone does not switch transports — --http or PORT selects HTTP. The HTTP layer is built on the mcp-use framework, which owns Streamable HTTP, the SSE stream, session management, and the OAuth discovery endpoints.

  • Hosted: https://mcp.agentphone.ai/mcp

  • Self-hosted HTTP: PORT=3000 npm start → http://localhost:3000/mcp

Authentication

  1. OAuth (recommended for end users): the framework proxies an Authorization Code + PKCE flow to the AgentPhone authorization server, so the client opens a browser to sign in at agentphone.ai — no key to paste. Enable it by setting MCP_OAUTH_CLIENT_ID (a client pre-registered with the AgentPhone AS). MCP_OAUTH_CLIENT_SECRET is optional: set it to run the gateway as a confidential client, or leave it unset to run as a public client (the gateway must then be registered with token_endpoint_auth_method=none). Public mode advertises none to downstream clients, which strict OAuth clients require.

  2. API key (scripts / single-tenant, OAuth off): each request sends Authorization: Bearer <your API key>. The server-side AGENTPHONE_API_KEY is only used for callers that send nothing, and only when AGENTPHONE_ALLOW_ANONYMOUS=true. Without that flag an unauthenticated call is rejected, so an exposed port cannot act as your account.

With OAuth enabled, bearer tokens are verified through the backend’s /auth/me; the anonymous opt-in does not bypass that verification.

The caller’s credential is forwarded to the AgentPhone REST API for validation. The optional anonymous mode instead uses the configured server API key.

Environment

Var

Purpose

PORT

HTTP port (default 3000)

AGENTPHONE_API_KEY

Fallback API key when OAuth is off. Only used for callers that send no Authorization header when AGENTPHONE_ALLOW_ANONYMOUS=true

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

MCP_OAUTH_CLIENT_ID

Enable OAuth; a gateway client pre-registered with the AgentPhone AS

MCP_OAUTH_CLIENT_SECRET

Optional. Set = confidential gateway; unset = public client (gateway registered with token_endpoint_auth_method=none, advertises none downstream)

AGENTPHONE_BASE_URL

API base (default https://api.agentphone.ai)

AGENTPHONE_OAUTH_AUTHORIZE

Override authorize/consent URL (default https://agentphone.ai/oauth/authorize)

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.

WAKESHIFT_KEY

Optional, HTTP only, with AGENTPHONE_EVENTS_SECRET. Turns on Wakeshift 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

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

Support matrix

Dimension

Supported

Transports

stdio (default) and Streamable HTTP (set PORT / --http)

Tested runtime

Node ^20.19.0 || >=22.12.0 (CI runs 20, 22, 24)

Clients

Any MCP client — verified with Cursor, Claude Desktop, Claude Code, Windsurf (stdio); Streamable-HTTP clients and remote agent platforms (HTTP)

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)

Channels

SMS and iMessage (send/receive); voice calls (webhook-driven or built-in AI)

Number types

US and Canada numbers

Highlights

  • Phone numbers — buy and manage numbers in any US/CA area code

  • SMS — send and receive text messages, view conversation threads

  • Voice calls — place outbound calls with built-in AI conversation (no webhook needed) or bring your own webhook

  • Inbound handling — set up webhooks to receive and respond to inbound calls and texts in real time

  • Agents — create agents with custom voices, system prompts, call transfer, and voicemail

  • Usage & billing — monitor number usage, message/call/webhook volume, and daily/monthly breakdowns

Authorization & safety

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

  • Greetings and prompts are sent as provided. The connector passes your greeting, topic, system prompt, opening line, and voicemail to the API as you write them, without adding wording of its own. You are responsible for any AI self-identification your use case or jurisdiction requires — put it in the greeting or the agent's instructions (e.g. a greeting that opens with "Hi, I'm Jordan's AI assistant calling to confirm your appointment").

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

All Tools (32)

Account

Tool

Description

account_overview

Get a full snapshot of your account — agents, numbers, webhook, and usage

get_usage

Get usage stats — number usage, billed SMS segments, and message/call/webhook volume. Use breakdown for daily or monthly time-series.

Phone Numbers

Tool

Description

list_numbers

List all phone numbers in your account

buy_number

Purchase a new phone number with optional area_code and agent_id

SMS

Tool

Description

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)

check_capabilities

Check which channels a phone number can receive (iMessage / SMS / RCS) before sending

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)

get_messages

Get messages for a specific number. Page older history with cursor (from nextCursor); before/after are optional time filters.

list_conversations

List SMS conversations. Pass agent_id to filter by agent.

get_conversation

Get a conversation with a bounded tail of recent messages

get_conversation_messages

Page through a conversation's full message history with cursor

update_conversation

Set metadata on a conversation

Contacts

Tool

Description

list_contacts

List saved contacts (address book). Filter with a search term.

manage_contact

Create, update, or delete a contact (set action). Delete requires confirm=true (previews first; cannot be undone)

Voice Calls

Tool

Description

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.

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)

end_call

End an in-progress call (safe to retry; ending a finished call is a no-op)

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)

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

Agents

Tool

Description

list_agents

List all agents with their numbers and voice config

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)

update_agent

Update an agent's configuration (incl. call-screening identity/purpose)

delete_agent

Delete an agent (numbers are kept but unassigned)

get_agent

Get agent details including phone numbers and voice config

attach_number

Assign a phone number to an agent

detach_number

Remove a phone number from an agent

list_voices

List available voices for agents

Webhooks

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.

Tool

Description

get_webhook

Get webhook configuration

set_webhook

Set a webhook URL for inbound messages and call events

delete_webhook

Remove a webhook

test_webhook

Send a test event to verify your webhook works

list_webhook_deliveries

View delivery history for debugging

get_webhook and set_webhook never return the signing secret, for either scope — it is always masked, so it can't land in model context, transcripts, or client logs. Retrieve the secret from the AgentPhone dashboard to verify webhook signatures.

Environment Variables

Variable

Required

Description

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

AGENTPHONE_ALLOW_ANONYMOUS

No

Explicit HTTP server-key fallback; default off, ignored when OAuth is enabled. See the self-hosting warning above

AGENTPHONE_BASE_URL

No

Override the API base URL (defaults to https://api.agentphone.ai)

PORT

No

Port for HTTP mode (defaults to 3000; set with PORT)

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

AGENTPHONE_EVENTS_SECRET

No

HTTP only, with WAKESHIFT_KEY. Signing secret for backend message notifications; see docs/backend-events.md

Development

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 — stdio by default; set PORT (or pass --http) for the HTTP server
npm test        # Build + run the full test suite (both transports, output-schema contracts)

Release & deployment checks

Command

What it verifies

npm run check:release

Version is identical across package.json, server.json, and the built handshake (run in prepublishOnly).

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

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.

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.

How It Works

This MCP server connects your AI assistant to the AgentPhone API. Your assistant talks to the MCP server, which calls the AgentPhone API, which talks to the phone network.

Your AI Assistant  <-->  agentphone-mcp  <-->  AgentPhone API  <-->  Phone Network

Outbound: your assistant places calls and sends texts through AgentPhone's API.

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.

License

MIT

Available Tools

28 tools
account_overviewA
Read-onlyIdempotent
Inspect

Get a complete snapshot of your AgentPhone account: agents, phone numbers, webhook status, and usage limits.

Inputs: no named parameters.

attach_numberB
Idempotent
Inspect

Attach a phone number to an agent so the agent handles calls/SMS on that number. Takes an agent ID and a phone number ID.

Inputs: agent_id (required), number_id (required).

buy_numberAInspect

Purchase a new phone number. This is a paid purchase that charges the account's balance. area_code requests a specific region (e.g. '415' for San Francisco); agent_id attaches it on purchase. Requires confirm=true to proceed.

Inputs: confirm, country, agent_id, area_code.

create_agentAInspect

Create a new agent. An agent owns phone numbers and handles calls/SMS.

A newly created agent has no phone number until one is attached. Set voice_mode to 'hosted' with a system_prompt for autonomous AI voice calls, or 'webhook' (default) to forward call transcripts to your webhook URL.

Inputs: name (required), voice, language, stt_mode, +14 more.

delete_agentA
Destructive
Inspect

Delete an agent permanently. Phone numbers attached to it are kept but unassigned. This cannot be undone.

Inputs: agent_id (required).

delete_webhookA
Destructive
Inspect

Remove a webhook. Pass agent_id to remove an agent's webhook (falls back to project default). Omit agent_id to remove the project-level webhook.

Inputs: agent_id.

detach_numberB
Idempotent
Inspect

Detach a phone number from an agent. The number is kept in your account but becomes unassigned.

Inputs: agent_id (required), number_id (required).

get_agentA
Read-onlyIdempotent
Inspect

Get details for a specific agent including its phone numbers, voice configuration, and instructions.

Inputs: agent_id (required).

get_callA
Read-onlyIdempotent
Inspect

Get details and transcript for a specific call, identified by its call ID. Pass wait=true to block until an in-progress call finishes before returning.

Inputs: call_id (required), wait, timeout.

get_conversationB
Read-onlyIdempotent
Inspect

Get a specific SMS conversation with full message history, identified by its conversation ID.

Inputs: conversation_id (required), message_limit.

get_messagesA
Read-onlyIdempotent
Inspect

Get SMS messages for a specific phone number, identified by its number ID. Returns individual messages rather than grouped conversation threads.

Inputs: number_id (required), limit.

get_usageA
Read-onlyIdempotent
Inspect

Get account usage statistics. By default returns a summary with number usage plus message, call, and webhook volume. Use breakdown='daily' or 'monthly' for time-series data.

Inputs: days, months, breakdown.

get_webhookA
Read-onlyIdempotent
Inspect

Get the webhook configuration. Pass agent_id to get an agent-specific webhook, or omit for the project-level default.

Inputs: agent_id.

list_agentsA
Read-onlyIdempotent
Inspect

List all agents with their phone numbers and voice configuration. An agent is required before you can make calls — it owns phone numbers and handles voice/SMS.

Inputs: limit.

list_callsA
Read-onlyIdempotent
Inspect

List recent calls. Scope by agent_id or number_id, or use status/direction/search to filter globally.

When agent_id or number_id is passed, status/direction/search filters are not applied. Returns call summaries including each call's ID, direction, participants, and status.

Inputs: limit, offset, search, status, +3 more.

list_contactsA
Read-onlyIdempotent
Inspect

List saved contacts (your address book). Optionally filter with a search term that matches name or phone number.

Inputs: limit, offset, search.

list_conversationsA
Read-onlyIdempotent
Inspect

List SMS conversations. Optionally filter by agent_id to see conversations for a specific agent.

Each conversation is a thread between your number and an external contact, with its ID, participant, message count, and last-message preview.

Inputs: limit, offset, agent_id.

list_numbersA
Read-onlyIdempotent
Inspect

List all phone numbers in your account, each with its ID, status, country, and assigned agent.

Inputs: limit, offset.

list_voicesA
Read-onlyIdempotent
Inspect

List available voices for agents. Each voice has a voice_id used in an agent's voice field.

Inputs: no named parameters.

list_webhook_deliveriesA
Read-onlyIdempotent
Inspect

View recent webhook delivery history. Shows which events were delivered, HTTP status codes, and timing.

Pass agent_id to see deliveries for that agent's webhook. Omit for project-level.

Inputs: hours, limit, agent_id.

make_callAInspect

Initiate an outbound, webhook-driven phone call where your backend handles the conversation logic.

The agent must have a phone number attached and a webhook configured. Every call automatically opens with an automated-assistant disclosure (added server-side and not removable).

Inputs: agent_id (required), to_number (required), voice, from_number_id, +1 more.

make_conversation_callAInspect

Place a phone call where the AI has an autonomous conversation about a given topic — scheduling, surveys, follow-ups, etc. No webhook setup needed.

The agent must have a phone number attached. Every call automatically opens with an automated-assistant disclosure (added server-side; cannot be disabled via topic or initial_greeting). By default this blocks until the call finishes and returns the full transcript. Set wait=false for fire-and-forget.

Inputs: topic (required), agent_id (required), to_number (required), wait, +4 more.

manage_contactA
Destructive
Inspect

Create, update, or delete a saved contact. Set action to choose the operation.

  • create: requires phone_number and name

  • update: requires contact_id; only the fields you pass are changed

  • delete: requires contact_id (permanent)

contact_id refers to a saved contact.

Inputs: action (required), name, email, notes, +2 more.

send_messageAInspect

Send an SMS or iMessage from one of your agent's phone numbers, or react to a message.

The agent must have at least one phone number attached. If the agent has multiple numbers, number_id or from_number selects which one to send from. iMessage extras (silently ignored on SMS): reply_to_message_id threads the reply under an earlier message, and send_style adds an expressive screen/bubble effect. To react to a message instead of sending one, set reaction and react_to_message_id (iMessage only); to_number and body are not needed in that case.

Inputs: body, agent_id, reaction, media_url, +7 more.

set_webhookA
Idempotent
Inspect

Set a webhook URL to receive inbound messages and call events.

Pass agent_id to set a webhook for a specific agent (overrides project default). Omit agent_id to set the project-level webhook for all agents. The webhook secret is returned — use it to verify signatures.

Inputs: url (required), timeout, agent_id, context_limit.

test_webhookA
Idempotent
Inspect

Send a test event to verify a webhook is working. Returns the HTTP status code and response time.

Pass agent_id to test that agent's webhook. Omit to test the project-level webhook.

Inputs: agent_id.

update_agentA
Idempotent
Inspect

Update an agent's configuration — name, description, voice settings, instructions, greeting, call transfer, or voicemail. Only provided fields are updated. Switching voice_mode to 'hosted' requires a system_prompt.

Inputs: agent_id (required), name, voice, language, +15 more.

update_conversationA
Idempotent
Inspect

Set metadata on a conversation. Use this to store custom state, tags, or context that persists between messages. Pass null to clear metadata.

Inputs: metadata (required), conversation_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools have clearly distinct resource+action targets, and the two call tools (make_call vs make_conversation_call) are well-differentiated by their descriptions. Minor overlap exists in the messaging domain where get_messages (raw per-number messages) could be confused with get_conversation (threaded history), but descriptions clarify the boundary.

    Naming Consistency4/5

    The set overwhelmingly follows a consistent verb_noun pattern (list_agents, create_agent, get_webhook, send_message). The main deviations are account_overview (noun-first) and manage_contact (a bundled multi-operation CRUD tool) versus the otherwise granular per-verb style.

    Tool Count3/5

    28 tools is on the heavy side of the recommended range, though the domain (agents, numbers, calls, SMS, conversations, contacts, webhooks, usage) is genuinely broad. Almost every tool earns its place with little redundancy, but the count pushes into borderline-heavy territory.

    Completeness4/5

    Coverage is strong: full CRUD for agents and contacts, complete webhook lifecycle (get/set/delete/test/deliveries), and call/message/conversation operations. The notable gap is the phone-number lifecycle — buy_number exists but there is no release/delete or update number operation.

    Maintenance

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to make real-world phone calls with AI voice technology and provides tools to track call status, transcripts, and summaries. It supports automated communication with both live numbers and simulated businesses for testing and demonstration purposes.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives AI agents phone numbers, email, SMS, and voice calls as MCP tools, enabling them to provision numbers, capture 2FA codes, send messages, and make calls.
      15
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to control PSTN phone calls via TelePath, including dialing, hangup, and phone number management.
      1
      10 npm
      MIT