---
title: "ThunderPhoneをMCPサーバーとして使用する"
description: "Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code、またはその他のStreamable HTTP MCPクライアントから、ThunderPhone音声エージェントを構築、テスト、検証、運用します。"
---

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

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

これは、[リモート MCP サーバーを音声エージェントに接続する](/ja/guides/mcp-servers)場合とは逆方向です。

| 方向 | 結果 |
| --- | --- |
| リモート MCP サーバー → ThunderPhone エージェント | 音声エージェントがリモートサーバーのツールを呼び出せます。 |
| ThunderPhone → MCP クライアント | コーディングエージェントで ThunderPhone を構築、テスト、運用できます。 |

## 認証

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

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

<Warning>
  `sk_live_` キーは組織データを読み取り、エージェントのデプロイ、通話の発信、番号の購入、キャンペーンの開始、リソースの削除など、本番環境での操作を実行できます。ブラウザーコード、リポジトリ、スクリーンショット、チャットログに含めないでください。クライアントのシークレットストアまたは環境変数のサポートを使用し、キーが露出した場合は直ちに取り消してください。
</Warning>

## CLI と stdio の代替手段

[ThunderPhone CLI](/ja/guides/cli) は、無関係なサーバーを保持したままクライアント設定を書き込めます。

```bash
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](/ja/guides/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回目の確認が求められます。[破壊的操作の確認](#confirming-destructive-actions)を参照してください。

### Claude Code

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

### Codex

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

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

### Cursor

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

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

### Claude Desktop

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

```json
{
  "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 の入力プロンプトでキーを入力します。

```json
{
  "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** はオープンワールドまたはネットワークとの連携を示します。ダッシュはヒントが設定されていないことを示します。

### 接続

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | 認証情報を検証し、組織と安全な認証情報メタデータを返します。 |

### エージェント

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | エージェントを一覧表示します。 |
| `get_agent` | `agent_id` | R, I | 1つのエージェントを取得します。 |
| `create_agent` | エージェント設定 | — | エージェントを作成します。 |
| `update_agent` | `agent_id`、変更フィールド | D | エージェントの下書きにフィールドをステージングし、下書き内の既存の値を置き換えます。確認手順なしで実行されます。`deploy_agent` を実行するまでデプロイ済みエージェントは変更されず、`discard_agent_draft` を実行すると下書きが元に戻ります。 |
| `deploy_agent` | `agent_id`、任意の `if_updated_at` | D, I | 下書きを本番環境に反映します。 |
| `discard_agent_draft` | `agent_id`、任意の `if_updated_at`、2回目のリクエストで `confirmation_token` | D, I | ステージング済みの変更を破棄します。2ステップです。[破壊的操作の確認](#confirming-destructive-actions)を参照してください。 |
| `duplicate_agent` | `agent_id`、任意の `name` | — | 組織内でエージェントを複製します。 |
| `delete_agent` | `agent_id`、2回目のリクエストで `confirmation_token` | D, I | エージェントを完全に削除します。2ステップです。 |
| `list_agent_versions` | `agent_id` | R, I | デプロイ済みの設定バージョンを一覧表示します。 |

### 電話番号と通信事業者

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | 組織の電話番号とルーティングを一覧表示します。 |
| `get_phone_number_limits` | — | R, I | 管理対象番号の使用状況と上限を取得します。 |
| `provision_phone_number` | 任意の `area_code`、`city`、`state`、`idempotency_key` | D, O | ThunderPhone 管理の着信番号を購入します。 |
| `list_voip_connections` | — | R, I | 接続されている顧客キャリアを一覧表示します。 |
| `search_voip_numbers` | `connection_id`、`country`、`type`、任意の `area_code` | R, I, O | キャリアの在庫を検索します。 |
| `import_voip_numbers` | `connection_id`、`numbers` | D, O | キャリアですでに所有している番号をインポートします。 |
| `update_phone_number` | `phone_number_id`、ルーティング／ラベル／Webhook フィールド | D | エージェントの割り当てを含む、番号のルーティングを更新します。 |
| `delete_phone_number` | `phone_number_id`、`confirm`、任意の `release_at_provider`、2 回目のリクエストでの `confirmation_token` | D, I, O | 番号を解放します。2 ステップです。 |

### SMS

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | 接続されたTwilioまたはTelnyxの番号を通じて、プレーンテキストのSMSを1件送信します。 |

### 通話

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_calls` | 任意のフィルター、`limit`、`offset` | R、I | RESTの通話履歴フィルターで通話を一覧表示します。 |
| `get_call` | `call_id` | R、I | 通話ステータスとメタデータを取得します。 |
| `get_call_transcript` | `call_id`、任意の`live` | R、I | 通話の文字起こしを取得します。 |
| `get_call_audio_url` | `call_id`、任意の`download` | R、I、O | 署名付き音声URLを返します。MCP経由で音声をストリーミングすることはありません。 |
| `get_call_grade` | `call_id` | R、I | 最新の通話評価を取得します。 |
| `place_call` | `agent_id`、`from_number`、`to_number` | D、O | 冪等ではない発信通話を1件実行します。 |
| `export_calls` | 通話フィルター、`export_format` | R、I | RESTエンドポイントの上限までJSONまたはCSVとしてエクスポートします。 |

### テストと検証

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | テストシナリオを一覧表示します。 |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, 任意の条件 | — | シナリオを作成します。 |
| `generate_test_scenarios` | `agent_id`, 任意の `count`、`include_edge_cases`、`locale` | O | エージェントプロンプトからシナリオを生成します。 |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, 任意の選択項目/マトリクス | D, O | ウェブまたは電話経由でシナリオを実行します。 |
| `get_test_run` | `agent_id`, `batch_id` | R, I | バッチのステータスとシナリオごとの結果を取得します。 |
| `list_validation_runs` | `agent_id` | R, I | 最近の下書き検証実行を一覧表示します。 |
| `get_validation_status` | `agent_id` | R, I | 最新の検証状態と下書き一致情報を取得します。 |

### ナレッジ

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | ナレッジベースを一覧表示します。 |
| `create_knowledge_base` | `name`、任意の `description` | — | ナレッジベースを作成します。 |
| `add_knowledge_document` | `knowledge_base_id`、`name`、`content` | — | テキストまたは Markdown を追加します。 |
| `import_knowledge_url` | `url`、任意の `name` | O | 安全な取り込みのために公開ページをキューに追加します。 |
| `search_knowledge` | `knowledge_base_id`、`query` | R, I | 本番の検索機能を通じて検索します。 |

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

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | HTTP 関数インテグレーションを一覧表示します。 |
| `create_integration` | `display_name`、関数 `spec`、任意のエンドポイントフィールド | — | HTTP ツールを作成します。認証ヘッダーはダッシュボードで追加します。 |
| `test_integration` | `url`、任意のメソッド/本文/タイムアウト、`header_names` を含む `integration_id`、2 回目のリクエストの `confirmation_token` | D, O | 制限付きで SSRF 保護されたテストリクエストを送信します。保存済みのヘッダー値はインテグレーションから入力され、そのホストにのみ送信されます。`POST`（デフォルト）、`PUT`、`PATCH`、`DELETE` は 2 ステップです。`GET` はすぐに実行されます。 |
| `list_webhook_endpoints` | — | R, I | 署名付き Webhook エンドポイントを一覧表示します。 |
| `list_webhook_deliveries` | 任意の `agent_id`、任意の `endpoint_id` | R, I | ペイロードを含まない最近の Webhook 配信結果を一覧表示します。 |
| `create_webhook_endpoint` | `label`、`url`、任意のイベント/ステータス | O | 署名付き Webhook エンドポイントを作成します。 |
| `test_webhook_endpoint` | `endpoint_id` | O | 通常の配信フローで合成イベントを送信します。 |
| `list_mcp_servers` | — | R, I | 音声エージェントから呼び出し可能なリモートサーバーを一覧表示します。 |
| `create_mcp_server` | `display_name`、`url` | O | リモートサーバーを登録して同期します。認証ヘッダーが必要なサーバーはダッシュボードで追加します。 |
| `sync_mcp_server_tools` | `server_id` | D, O | リモートサーバーのツールカタログを更新します。 |

### キャンペーン

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | 発信キャンペーンを一覧表示します。 |
| `create_campaign` | キャンペーンフィールド | — | 下書きキャンペーンを作成します。 |
| `add_campaign_contacts` | `campaign_id`、`contacts` | — | 最大5,000件の JSON 連絡先を追加します。 |
| `campaign_action` | `campaign_id`、`action`、任意の `consent_to_charge`、2回目のリクエストでは `confirmation_token` | D, O | `start`、`pause`、`resume`、または `stop` を実行します。`start` と `resume` は2段階操作です。`pause` と `stop` は即時に実行されます。 |
| `get_campaign_stats` | `campaign_id` | R, I | カウンターと最近の結果を取得します。 |

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

| ツール | 主な引数 | 注釈 | 機能 |
| --- | --- | --- | --- |
| `list_voices` | — | R、I | 音声と対応言語を一覧表示します。 |
| `preview_voice` | `voice`, `language`, `text` | O | サンプルを生成し、署名付き URL を返します。 |
| `list_voice_clones` | — | R、I | カスタム音声クローンを一覧表示します。 |
| `get_billing_summary` | — | R、I | 残高と正式なティア価格を取得します。支払いの変更操作は公開されません。 |
| `search_docs` | `query`、任意の `limit` | R、I、O | 公開ドキュメントのインデックスを検索します。 |
| `get_doc_page` | `path` | R、I、O | 公開されている Markdown ドキュメントページを 1 件取得します。 |

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

## 破壊的操作の確認

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

```json
{
  "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` は、公開キャッシュ済みの参照情報を公開します。

| URI | 内容 |
| --- | --- |
| `thunderphone://docs/llms.txt` | 公開ドキュメントのインデックス。 |
| `thunderphone://docs/quickstart` | クイックスタートの Markdown。 |
| `thunderphone://pricing` | 現在の公開料金の Markdown。 |

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 ブロックが含まれます。

```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` の無効なリクエストエラーを返します。