Agentphone

AgentPhone MCP Server

Model Context Protocol を通じて、AI エージェントに実際の電話番号、SMS、音声通話を提供します。

AgentPhone を使うと、Cursor、Claude Desktop、その他の MCP 対応クライアントで、自然言語を通じて AI エージェントが電話番号を購入したり、SMS を送受信したり、音声通話を発信したりできます。

エージェントが中心的な概念です。各エージェントは、それぞれ専用の電話番号、音声の個性、システムプロンプト、Webhook を持ちます。エージェントは、専用の電話回線を持つ仮想のチームメンバーと考えることができます。目的（サポート、営業、スケジュール調整など）に応じてエージェントを作成し、通話中の話し方や振る舞いを設定できます。

クイックスタート

1. API キーを取得する

agentphone.ai でサインアップし、Settings から API キーを作成します。

2. MCP 経由で接続する

オプション A：リモートサーバー（推奨）

MCP クライアントの接続先にホストされたエンドポイントを指定します。インストールは不要です。

{
  "mcpServers": {
    "agentphone": {
      "type": "streamable-http",
      "url": "https://mcp.agentphone.ai/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Streamable HTTP トランスポートに対応する MCP クライアント（Switchboard、リモートエージェントプラットフォームなど）であれば、どれでも利用できます。

オプション B：ローカルサーバー（stdio）

npx 経由でローカル実行します。Cursor、Claude Desktop、Windsurf、Claude Code で利用できます。

Cursor： Settings > MCP または ~/.cursor/mcp.json Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "agentphone": {
      "command": "npx",
      "args": ["-y", "agentphone-mcp"],
      "env": {
        "AGENTPHONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

オプション C：セルフホスト型 HTTP サーバー

独自の HTTP MCP エンドポイントを実行します。

PORT=3000 npx agentphone-mcp --http

その後、http://localhost:3000/mcp に接続し、各リクエストに Authorization: Bearer <your AgentPhone API key> を付けて送信するように MCP クライアントを設定します。サーバー側の AGENTPHONE_API_KEY だけでは、HTTP 呼び出し元は認証されません。

警告： AGENTPHONE_ALLOW_ANONYMOUS=true を有効にすると、OAuth がオフの場合に限り、Authorization ヘッダーのないリクエストに対してサーバーの AGENTPHONE_API_KEY を使用します。そのエンドポイントにアクセスできる人は誰でもアカウントを操作できるため、この設定は必ず独自の認証の背後でのみ有効にしてください。不正な形式のヘッダーは拒否され、呼び出し元が指定した bearer がサーバーキーに置き換えられることはありません。

できること

設定が完了したら、AI エージェントに次のように頼むだけです。

• 「415 の市外局番で電話番号を購入して」
• 「電話をかけてきた人に挨拶し、請求に関するサポートをするエージェントを作成して」
• 「+14155551234 に電話して、歯科の予約について会話して」
• 「+14155551234 に『明日午後3時の予約が確定しました』とテキストを送って」
• 「最近の通話と文字起こしを表示して」
• 「利用可能な音声を一覧表示して、エージェントの音声を別のものに変更して」
• 「誰かが私の番号に電話またはテキストを送信したときに通知が届くよう、Webhook を設定して」
• 「今月の使用状況の内訳を表示して」

トランスポートとホスティング

このサーバーは mcp-use サーバーフレームワーク上に構築されており、HTTP レイヤー（Streamable HTTP、SSE ストリーム、セッション管理、OAuth ディスカバリーエンドポイント）を担います。npm start（または Docker イメージ）を実行すると、PORT（デフォルトは 3000）で HTTP サーバーが起動し、/mcp でアクセスできます。

• ホスト型： https://mcp.agentphone.ai/mcp
• セルフホスト： PORT=3000 npm start → http://localhost:3000/mcp

認証

1. OAuth（エンドユーザーに推奨）： フレームワークは Authorization Code + PKCE フローを AgentPhone 認可サーバーにプロキシするため、クライアントはブラウザーを開いて agentphone.ai にサインインします。キーを貼り付ける必要はありません。MCP_OAUTH_CLIENT_ID（AgentPhone AS に事前登録されたクライアント）を設定すると有効になります。MCP_OAUTH_CLIENT_SECRET は任意です。ゲートウェイを機密クライアントとして実行する場合は設定し、パブリッククライアントとして実行する場合は設定しないでください（その場合、ゲートウェイは token_endpoint_auth_method=none で登録する必要があります）。パブリックモードでは下流クライアントに none を通知します。これは、厳格な OAuth クライアントで必須です。
2. API キー（スクリプト／単一テナント、OAuth 無効）： 各リクエストで Authorization: Bearer <your API key> を送信します。サーバー側の AGENTPHONE_API_KEY は、認証情報を送信しない呼び出し元に対してのみ使用され、かつ AGENTPHONE_ALLOW_ANONYMOUS=true の場合に限られます。このフラグがなければ、認証されていない呼び出しは拒否されるため、ポートが外部に公開されてもアカウントを操作されることはありません。

OAuth が有効な場合、ベアラートークンはバックエンドの /auth/me を通じて検証されます。匿名アクセスのオプトインによって、この検証が省略されることはありません。

呼び出し元の認証情報は、検証のため AgentPhone REST API に転送されます。任意の匿名モードでは、代わりに設定済みのサーバー API キーが使用されます。

環境変数

変数	用途
PORT	HTTP ポート（デフォルトは 3000）
AGENTPHONE_API_KEY	OAuth が無効な場合のフォールバック API キー。AGENTPHONE_ALLOW_ANONYMOUS=true のときに、Authorization ヘッダーを送信しない呼び出し元に対してのみ使用されます
AGENTPHONE_ALLOW_ANONYMOUS	デフォルトではオフ。OAuth が有効な場合は無視されます。true に設定すると、Authorization ヘッダーのないリクエストでサーバーの AGENTPHONE_API_KEY を使用できます。その場合、ポートにアクセスできる人は誰でもアカウントを操作できるため、まずサーバーを独自の認証の背後に配置してください
MCP_OAUTH_CLIENT_ID	OAuth を有効にします。AgentPhone AS に事前登録されたゲートウェイクライアントです
MCP_OAUTH_CLIENT_SECRET	任意。設定すると機密ゲートウェイになり、未設定の場合はパブリッククライアントになります（ゲートウェイは token_endpoint_auth_method=none で登録され、下流に none を通知します）
AGENTPHONE_BASE_URL	API のベース URL（デフォルトは https://api.agentphone.ai）
AGENTPHONE_OAUTH_AUTHORIZE	認可／同意 URL を上書きします（デフォルトは https://agentphone.ai/oauth/authorize）
AGENTPHONE_MCP_PUBLIC_URL	このサーバーへのアクセスに使う公開ベース URL。/.well-known/mcp.json インストールマニフェストで通知されます（例：https://mcp.agentphone.ai）。未設定の場合はリクエストから導出されます。

主な機能

• 電話番号 — 米国／カナダの任意の市外局番で電話番号を購入・管理できます
• SMS — テキストメッセージの送受信や、会話スレッドの表示ができます
• 音声通話 — 組み込みの AI 会話機能を使って発信できます（Webhook は不要）。または独自の Webhook を利用できます
• 着信処理 — Webhook を設定して、着信や受信テキストをリアルタイムで受け取り、応答できます
• エージェント — カスタム音声、システムプロンプト、通話転送、留守番電話を備えたエージェントを作成できます
• 使用状況と請求 — 電話番号の使用状況、メッセージ／通話／Webhook の件数、日次／月次の内訳を確認できます

全ツール（28）

アカウント

ツール	説明
account_overview	エージェント、電話番号、Webhook、使用状況を含むアカウント全体のスナップショットを取得します
get_usage	使用状況の統計を取得します。電話番号の使用状況、課金対象の SMS セグメント、メッセージ／通話／Webhook の件数を確認できます。日次または月次の時系列データには breakdown を使用します。

電話番号

ツール	説明
list_numbers	アカウント内のすべての電話番号を一覧表示します
buy_number	任意の area_code と agent_id を指定して、新しい電話番号を購入します

SMS

ツール	説明
send_message	SMS または iMessage を送信します。メディア、スレッド形式の返信（reply_to_message_id）、iMessage の送信エフェクト（send_style）、グループチャットに対応しています
get_messages	特定の番号のメッセージを取得します
list_conversations	SMS の会話を一覧表示します。エージェントで絞り込むには、agent_id を指定します。
get_conversation	メッセージ履歴全体を含む会話を取得します
update_conversation	会話のメタデータを設定します

連絡先

ツール	説明
list_contacts	保存済みの連絡先（アドレス帳）を一覧表示します。search の語句で絞り込めます。
manage_contact	連絡先を作成、更新、または削除します（action を設定）

音声通話

ツール	説明
list_calls	通話を一覧表示します。agent_id、number_id、ステータス、方向、またはキーワードで絞り込めます。
get_call	通話の詳細と文字起こしを取得します
make_call	発信します（Webhook による制御）
make_conversation_call	組み込みの AI 会話機能で通話を発信します — Webhook は不要です

エージェント

ツール	説明
list_agents	電話番号と音声設定を含む、すべてのエージェントを一覧表示します
create_agent	音声、システムプロンプト、通話転送、ボイスメール、音声の調整（速度、割り込み感度、相づち、言語など）を設定してエージェントを作成します
update_agent	エージェントの設定を更新します
delete_agent	エージェントを削除します（電話番号は割り当て解除された状態で保持されます）
get_agent	電話番号や音声設定など、エージェントの詳細を取得します
attach_number	電話番号をエージェントに割り当てます
detach_number	電話番号のエージェントへの割り当てを解除します
list_voices	エージェントで利用可能な音声を一覧表示します

Webhook

すべての Webhook ツールでは、agent_id を任意で指定できます。エージェント固有の Webhook を管理する場合は指定し、省略するとプロジェクトレベルのデフォルトが対象になります。エージェントの Webhook は、プロジェクトレベルの Webhook より優先されます。

ツール	説明
get_webhook	Webhook の設定を取得します
set_webhook	受信メッセージと通話イベント用の Webhook URL を設定します
delete_webhook	Webhook を削除します
test_webhook	Webhook が機能することを確認するため、テストイベントを送信します
list_webhook_deliveries	デバッグ用に配信履歴を表示します

get_webhook と set_webhook は、どちらのスコープでも署名シークレットをデフォルトでマスクします。 可能な場合はダッシュボードからシークレットを取得してください。reveal_secret: true を渡すと、シークレットがツールの出力に含まれ、モデルコンテキスト、文字起こし、クライアントログに公開されます。 これにより偶発的な漏えいを防ぎますが、意図的にシークレットを要求するモデルに対する認可境界ではありません。

環境変数

変数	必須	説明
AGENTPHONE_API_KEY	stdio：必須、HTTP 匿名モード：必須	HTTP モードでは、AGENTPHONE_ALLOW_ANONYMOUS=true、OAuth が無効、かつ呼び出し元の Authorization ヘッダーがない場合にのみ使用されます
AGENTPHONE_ALLOW_ANONYMOUS	いいえ	HTTP サーバーキーへの明示的なフォールバックです。デフォルトでは無効で、OAuth が有効な場合は無視されます。上記のセルフホストに関する警告を参照してください
AGENTPHONE_BASE_URL	いいえ	API のベース URL を上書きします（デフォルトは https://api.agentphone.ai）
PORT	いいえ	HTTP モードのポートです（デフォルトは 3000。PORT で設定します）

開発

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)

仕組み

この MCP サーバーは、AI アシスタントを AgentPhone API に接続します。アシスタントが MCP サーバーにリクエストを送信し、MCP サーバーが AgentPhone API を呼び出し、AgentPhone API が電話網と通信します。

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

発信：アシスタントは AgentPhone の API を通じて通話を発信し、テキストメッセージを送信します。

着信：誰かがあなたの番号に電話またはテキストメッセージを送ると、AgentPhone は Webhook イベントをあなたのサーバーに送信します。プログラムから応答するか、エージェントに組み込まれた AI に処理させることができます。

ライセンス

MIT