---
title: "將 ThunderPhone 用作 MCP 伺服器"
description: "透過 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他支援串流 HTTP 的 MCP 用戶端，建立、測試、驗證及營運 ThunderPhone 語音智能體。"
---

ThunderPhone 在以下位置提供可串流 HTTP Model Context Protocol 伺服器：

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

這與[將遠端 MCP 伺服器連接至語音智能體](/yue/guides/mcp-servers)的方向相反：

| 方向 | 結果 |
| --- | --- |
| 遠端 MCP 伺服器 → ThunderPhone 智能體 | 語音智能體可以呼叫遠端伺服器的工具。 |
| ThunderPhone → 你的 MCP 用戶端 | 你的程式開發智能體可以建立、測試及操作 ThunderPhone。 |

## 驗證身分

目錄用戶端預設使用 [OAuth](/yue/guides/oauth)：登入、選擇組織，並批准所要求的權限。你可以在 **組織 → API 金鑰 → 已授權應用程式** 撤銷存取權。

如用戶端設定為使用 API 金鑰，請在 **組織 → 金鑰** 建立 `sk_live_` 金鑰，並以 `THUNDERPHONE_API_KEY` 向 MCP 用戶端提供。該金鑰會綁定至單一組織；由其他組織擁有的識別碼會被視為找不到。

<Warning>
  `sk_live_` 金鑰可以讀取組織資料，並執行部署智能體、撥打電話、購買號碼、啟動推廣活動及刪除資源等正式環境操作。請勿將其放入瀏覽器程式碼、儲存庫、截圖及聊天記錄。請使用用戶端的密鑰儲存區或環境變數支援，並在金鑰外洩後立即撤銷。
</Warning>

## CLI 與 stdio 替代方案

[ThunderPhone CLI](/yue/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](/yue/guides/oauth) 登入，無需使用 API 金鑰。如你尚未擁有 ThunderPhone 帳戶，請在登入頁面選擇 **建立帳戶**；完成電郵驗證後，系統會返回授權畫面。

### Claude（網頁版、桌面版及流動版）

1. 開啟 **設定 → 連接器**。如 ThunderPhone 出現在連接器目錄中，請選擇它。否則，選擇 **新增自訂連接器**，命名為 `ThunderPhone`，並輸入 `https://api.thunderphone.com/v1/mcp`。
2. 選擇 **連接**，登入 ThunderPhone，選取組織，然後批准權限。
3. 在對話中，從工具選單啟用 ThunderPhone，並提出你的需求，例如「列出我的智能體」。

自訂連接器需要付費 Claude 方案。Team 及 Enterprise 方案的擁有者須先在組織的連接器設定中新增連接器，其後每位成員可連接自己的 ThunderPhone 帳戶。

### ChatGPT

1. 如 ThunderPhone 出現在 ChatGPT 應用程式目錄中，請選擇並連接。
2. 否則，開啟 **設定 → 應用程式及連接器 → 進階設定**，啟用 **開發人員模式**，然後以 URL `https://api.thunderphone.com/v1/mcp` 及 OAuth 驗證建立連接器。
3. 登入 ThunderPhone，選取組織，然後批准權限。從工具選單將 ThunderPhone 加入對話。

刪除智能體或電話號碼、捨棄草稿，以及啟動推廣活動時，兩個應用程式均會要求再次確認；請參閱[確認破壞性操作](#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** 代表開放世界／網絡互動。破折號代表未設定提示。

### 智能體

| 工具 | 主要參數 | 註釋 | 功能 |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | 列出智能體。 |
| `get_agent` | `agent_id` | R, I | 取得單一智能體。 |
| `create_agent` | 智能體設定 | — | 建立智能體。 |
| `update_agent` | `agent_id`、已變更欄位 | — | 在智能體草稿中暫存欄位。 |
| `deploy_agent` | `agent_id`、可選的 `if_updated_at` | I | 將草稿發佈至正式環境。 |
| `discard_agent_draft` | `agent_id`、可選的 `if_updated_at`、第二次請求時的 `confirmation_token` | D, I | 捨棄已暫存的變更。分兩步進行，請參閱[確認破壞性操作](#confirming-destructive-actions)。 |
| `duplicate_agent` | `agent_id`、可選的 `name` | — | 在組織內複製智能體。 |
| `delete_agent` | `agent_id`、第二次請求時的 `confirmation_token` | D, I | 永久刪除智能體。分兩步進行。 |
| `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` | 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` | O | 匯入已由電訊商持有的號碼。 |
| `update_phone_number` | `phone_number_id`、路由／標籤／webhook 欄位 | — | 更新號碼路由，包括智能體指派。 |
| `delete_phone_number` | `phone_number_id`、`confirm`、可選的 `release_at_provider`、第二次請求時的 `confirmation_token` | D, I, O | 釋放號碼。分兩步進行。 |

### 通話

| 工具 | 主要參數 | 註釋 | 功能 |
| --- | --- | --- | --- |
| `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` | O | 撥出一次非冪等的外撥電話。 |
| `export_calls` | 通話篩選條件、`export_format` | R, I | 以 JSON 或 CSV 匯出最多達 REST 端點上限的資料。 |

### 測試及驗證

| 工具 | 主要參數 | 註釋 | 功能 |
| --- | --- | --- | --- |
| `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`、可選的選擇／矩陣 | 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`、可選的方法／標頭／主體／逾時設定 | O | 傳送受限制並受 SSRF 保護的測試請求。 |
| `list_webhook_endpoints` | — | 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` | O | 重新整理遠端伺服器的工具目錄。 |

### 推廣活動

| 工具 | 主要參數 | 註釋 | 功能 |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | 列出外撥推廣活動。 |
| `create_campaign` | 推廣活動欄位 | — | 建立推廣活動草稿。 |
| `add_campaign_contacts` | `campaign_id`、`contacts` | — | 最多新增 5,000 個 JSON 聯絡人。 |
| `campaign_action` | `campaign_id`、`action`、可選的 `consent_to_charge`、第二次請求時的 `confirmation_token` | D, O | 執行 `start`、`pause`、`resume` 或 `stop`。`start` 及 `resume` 分兩步進行；`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 | 取得餘額及具權威性的級別價格；不會提供付款變更操作。 |
| `create_agent_import` | `vendor`、`vendor_key` | O | 開始加密匯入 Vapi、Retell、ElevenLabs 或 Bland。 |
| `get_agent_import` | `public_id` | R, I | 取得建議的匯入差異。 |
| `commit_agent_import` | `public_id` | — | 根據已審核的計劃提交所選智能體。 |
| `search_docs` | `query`、可選的 `limit` | R, I, O | 搜尋公開文件索引。 |
| `get_doc_page` | `path` | R, I, O | 擷取單一公開 Markdown 文件頁面。 |

所有產品工具均使用與公開 API 相同的 REST 程式碼路徑。因此，REST 驗證、組織範圍限定、角色、帳單准入、配額、TCPA 確認、供應商安全及稽核行為均維持不變。

## 確認破壞性操作

標記為 D 的工具會變更或移除無法還原的內容，或開始致電真人。這些工具需要兩次請求。第一次請求不會作出任何變更，並會回傳：

```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 分鐘，且只適用於一個組織、一個工具及一組完全相同的引數，因此刪除三個智能體需要三次確認。使用 `pause` 或 `stop` 的 `campaign_action` 會略過此步驟，確保執行中的推廣活動可隨時立即停止。

## 入門提示

`prompts/list` 提供六個可重複使用的工作流程：

- `create_inbound_receptionist`
- `run_agent_tests`
- `import_vapi_assistants`
- `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。 |

使用 `resources/read` 讀取資源。公開擷取使用較短的逾時設定、2 MiB 上限，以及程序內 10 分鐘快取。

## 協定與錯誤

伺服器支援協定版本 `2025-06-18` 及 `2025-03-26`；會回應受支援的客戶端版本，否則選用 `2025-06-18`。伺服器實作了 `initialize`、`ping`、工具、提示、資源及通知。通知會回傳 `202 Accepted`。此無狀態伺服器不提供 SSE 監聽器或工作階段刪除功能，因此 `GET` 及 `DELETE` 會回傳 `405 Method Not Allowed`，並附帶 `Allow: POST`。

工具失敗仍會以帶有 `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`。MCP `2025-06-18` 不支援 JSON-RPC 批次請求，並會回傳清晰的 `-32600` 無效請求錯誤。