ThunderPhoneをMCPサーバーとして使用する

Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code、またはその他のStreamable HTTP MCPクライアントから、ThunderPhone音声エージェントを構築、テスト、検証、運用します。

ThunderPhone は、以下の場所で Streamable HTTP Model Context Protocol サーバーを公開しています。

https://api.thunderphone.com/v1/mcp

これは、リモート MCP サーバーを音声エージェントに接続する場合とは逆方向です。

認証#

ディレクトリクライアントでは、デフォルトで OAuth を使用します。ログインし、組織を選択して、要求された権限を承認します。アクセス権は 組織 → APIキー → 承認済みアプリ で取り消します。

APIキーで設定されたクライアントでは、組織 → キー で sk_live_ キーを作成し、THUNDERPHONE_API_KEY として MCP クライアントに公開します。キーは1つの組織に紐付けられます。別の組織が所有する ID は見つからないものとして扱われます。

CLI と stdio の代替手段#

ThunderPhone CLI は、無関係なサーバーを保持したままクライアント設定を書き込めます。

npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user

@thunderphone/mcp をグローバルインストールした後は、同じオプションで thunderphone-mcp setup を使用します。セットアップは Claude Code、Codex、Cursor、VS Code、Gemini、Claude Desktop、Windsurf をサポートしています。直接 HTTP が推奨されます。Desktop では stdio を使用します。

stdio 対応クライアントでは、command: "npx" と args: ["-y", "@thunderphone/mcp"] を設定します。ラッパーはまず THUNDERPHONE_API_KEY を使用し、次に thunderphone login の認証情報を使用して期限切れのトークンを更新し、その後 mcp-remote 経由で OAuth を使用します。デバイスログインと OAuth には、対応する API OAuth の提供開始が必要です。APIキーの経路には必要ありません。直接 HTTP の設定では CLI 認証情報ストアを読み取りません。デバイスログインを再利用するには stdio ラッパーを使用します。

これらは、以下の手動クライアント設定の代替手段です。

クライアント設定#

Claude と ChatGPT は OAuth でログインするため、API キーは不要です。ThunderPhone アカウントをまだ作成していない場合は、ログインページで アカウントを作成 を選択します。メールアドレスの確認後、承認画面に戻ります。

Claude（ウェブ、デスクトップ、モバイル）#

1. カスタマイズ → コネクタ を開きます（旧バージョンでは 設定 → コネクタ）。コネクタディレクトリに ThunderPhone が表示されている場合は選択します。表示されない場合は カスタムコネクタを追加 を選択し、名前を ThunderPhone、URL を https://api.thunderphone.com/v1/mcp として入力します。
2. 接続 を選択し、ThunderPhone にログインして組織を選択し、権限を承認します。
3. チャットでツールメニューから ThunderPhone を有効にし、必要な操作を依頼します。例: 「エージェントを一覧表示」。

Claude は各ツールを初めて使用する前に確認を求めます。ほとんどの確認を省略するには、カスタマイズ → コネクタ → ThunderPhone を開き、読み取り専用ツール を常に許可するよう設定します。これらのツールは、エージェント、通話、文字起こし、残高、ドキュメントを参照するだけです。変更が実行される前に毎回確認したい場合は、書き込み/削除ツール を承認が必要な設定のままにします。

カスタムコネクタには有料の Claude プランが必要です。Team および Enterprise プランでは、まずオーナーが組織のコネクタ設定でコネクタを追加し、その後各メンバーが自身の ThunderPhone アカウントを接続します。

ChatGPT#

1. ChatGPT のアプリディレクトリに ThunderPhone が表示されている場合は、選択して接続します。
2. 表示されない場合は 設定 → アプリとコネクタ → 詳細設定 を開き、開発者モード を有効にして、URL https://api.thunderphone.com/v1/mcp と OAuth 認証を使用するコネクタを作成します。
3. ThunderPhone にログインし、組織を選択して権限を承認します。ツールメニューからチャットに ThunderPhone を追加します。

エージェントまたは電話番号の削除、下書きの破棄、キャンペーンの開始、外部システムに書き込み可能なテストリクエストの送信では、どちらのアプリでも2回目の確認が求められます。破壊的操作の確認を参照してください。

Claude Code#

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex#

以下を ~/.codex/config.toml に追加します。

[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"

Cursor#

.cursor/mcp.json を作成します。

{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Claude Desktop#

Claude Desktop の設定に mcp-remote ブリッジを追加します。

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code#

.vscode/mcp.json を作成し、VS Code の入力プロンプトでキーを入力します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}

ツール#

すべてのツールには MCP 注釈が付いています。表内の R は読み取り専用、D は破壊的操作、I はべき等、O はオープンワールドまたはネットワークとの連携を示します。ダッシュはヒントが設定されていないことを示します。

接続#

エージェント#

電話番号と通信事業者#

SMS#

通話#

テストと検証#

ナレッジ#

連携、Webhook、リモート MCP サーバー#

キャンペーン#

音声、請求、ドキュメント#

すべての製品ツールは、公開 API と同じ REST コードパスを使用します。したがって、REST 検証、組織スコープ、ロール、請求承認、クォータ、TCPA 確認、プロバイダー安全性、監査動作は変更なく適用されます。

破壊的操作の確認#

D とマークされたツールは、何かを変更または削除するか、実在の人物への発信を開始します。元に戻せない操作には、2 回のリクエストが必要です。最初のリクエストでは何も変更されず、次を返します。

{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}

アシスタントは影響を受ける内容をユーザーに示し、確認を求めます。その後、同じ引数に confirmation_token を追加してリクエストを繰り返します。トークンは 10 分間有効で、1 つの組織、1 つのツール、および 1 組の完全に一致する引数に対してのみ有効です。そのため、3 つのエージェントを削除するには 3 回の確認が必要です。pause または stop を指定した campaign_action はこの手順をスキップするため、実行中のキャンペーンは常にすぐに停止できます。GET を指定した test_integration も同様です。一部の D ツールは 1 回のリクエストで実行されます。これは、D がサーバー側の確認ではなく、その操作の影響を示すためです。update_agent は下書きの内容を置き換えます（discard_agent_draft で元に戻せます）。deploy_agent は本番設定を置き換え、update_phone_number は進行中の通話を再ルーティングし、sync_mcp_server_tools はリモートサーバーのツールカタログを置き換えます。import_voip_numbers は番号を通信事業者に再割り当てし、run_agent_tests はクレジットを消費する可能性があります。send_sms と place_call は実在の人物に連絡します（place_call には独自の同意確認があります）。provision_phone_number は番号を購入します。MCP クライアントは、これらの操作についても承認を求める場合があります。

スタータープロンプト#

prompts/list は、再利用可能な5つのワークフローを提供します。

• create_inbound_receptionist
• run_agent_tests
• buy_and_attach_number
• review_low_grade_calls
• add_url_to_agent_knowledge

一覧にあるプロンプト名と宣言された引数を指定して prompts/get を使用すると、すぐに実行できるユーザーメッセージを取得できます。

リソース#

resources/list は、公開キャッシュ済みの参照情報を公開します。

1 件を resources/read で読み取ります。公開フェッチでは、短いタイムアウト、2 MiB の上限、プロセス内で 10 分間のキャッシュを使用します。

プロトコルとエラー#

サーバーはプロトコルバージョン 2025-06-18 と 2025-03-26 をサポートします。サポート対象のクライアントバージョンをエコーし、それ以外の場合は 2025-06-18 を選択します。initialize、ping、ツール、プロンプト、リソース、通知を実装しています。通知は 202 Accepted を返します。このステートレスサーバーは SSE リスナーまたはセッション削除を公開しないため、GET と DELETE は Allow: POST を伴う 405 Method Not Allowed を返します。

ツールの失敗は、isError: true を含む成功した JSON-RPC レスポンスとして返されます。テキストには短い文に続いて JSON ブロックが含まれます。

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

place_call では、固有の outbound_tcpa_confirmation_required: プレフィックスが維持されます。不明な JSON-RPC メソッドは、HTTP 200 レスポンス内で -32601 を返します。JSON-RPC バッチは MCP 2025-06-18 でサポートされておらず、明確な -32600 の無効なリクエストエラーを返します。