---
title: "將 ThunderPhone 用作 MCP 伺服器"
description: "從 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他 Streamable HTTP MCP 用戶端建置、測試、驗證及營運 ThunderPhone 語音智慧體。"
---

ThunderPhone 提供可串流 HTTP 模型情境協定伺服器，位於：

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

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

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

## 驗證身分

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

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

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

## CLI 與 stdio 替代方案

[ThunderPhone CLI](/zh-Hant/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 為首選；桌面版使用 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](/zh-Hant/guides/oauth) 登入，不需要 API 金鑰。若你尚未擁有 ThunderPhone 帳號，請在登入頁面選擇 **建立帳號**；完成電子郵件驗證後，系統會帶你返回授權畫面。

### Claude（網頁版、桌面版與行動版）

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

Claude 首次使用各項工具前都會先詢問。若要略過大部分提示，請開啟 **自訂 → 連接器 → 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

將 `mcp-remote` 橋接器加入 Claude Desktop 設定：

```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 | 取得單一智慧體。 |
| `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`、第二次請求時的 `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` | 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`，以及第二次請求中的 `confirmation_token` | D, I, O | 釋出號碼。需分兩個步驟。 |

### 簡訊

| 工具 | 主要引數 | 註解 | 功能 |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | 透過已連接的 Twilio 或 Telnyx 號碼傳送一則純文字 SMS。 |

### 通話

| 工具 | 主要引數 | 註記 | 功能 |
| --- | --- | --- | --- |
| `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 | 撥打一通非冪等的外撥電話。 |
| `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`、選用的選取項目／矩陣 | 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`、第二次請求時的 `confirmation_token` | D, O | 傳送受限且受 SSRF 保護的測試請求。已儲存的標頭值會從整合中帶入，且只會傳送至其自身主機。`POST`（預設）、`PUT`、`PATCH` 與 `DELETE` 採兩步驟執行；`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`、第二次請求時的 `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 | 取得餘額與權威方案價格；不會公開任何付款異動操作。 |
| `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` 會略過此步驟，以便隨時立即停止正在執行的行銷活動；使用 `GET` 的 `test_integration` 也是如此。部分 D 工具可在一次請求中執行，因為 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` 提供五個可重複使用的工作流程：

- `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。 |

使用 `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` 無效請求錯誤。