Open in

將 ThunderPhone 用作 MCP 伺服器

從 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他 Streamable HTTP MCP 用戶端建置、測試、驗證及營運 ThunderPhone 語音智慧體。

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

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

這與將遠端 MCP 伺服器連接至語音智慧體的方向相反：

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

驗證身分

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

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

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 為首選；桌面版使用 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（網頁版、桌面版與行動版）

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

Claude 首次使用各項工具前都會先詢問。若要略過大部分提示，請開啟 自訂 → 連接器 → ThunderPhone，並將 唯讀工具 設為一律允許。這些工具僅會查詢資訊：智慧體、通話、逐字稿、餘額與文件。若你希望在每項變更發生前先查看，請讓 寫入／刪除工具 維持需要核准。

自訂連接器需要付費 Claude 方案。在 Team 和 Enterprise 方案中，擁有者必須先在組織的連接器設定下新增連接器，之後每位成員再連結自己的 ThunderPhone 帳號。

ChatGPT

若 ThunderPhone 出現在 ChatGPT 應用程式目錄中，請選取並連線。
否則，開啟 設定 → 應用程式與連接器 → 進階設定，啟用 開發人員模式，並以 URL https://api.thunderphone.com/v1/mcp 和 OAuth 驗證建立連接器。
登入 ThunderPhone，選取組織，然後核准權限。從工具選單將 ThunderPhone 加入聊天。

刪除智慧體或電話號碼、捨棄草稿、啟動行銷活動，以及傳送可寫入外部系統的測試請求時，兩個應用程式都會要求你進行第二次確認；請參閱確認破壞性操作。

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

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

{
  "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 表示開放世界／網路互動。破折號表示未設定提示。

連線

工具	主要引數	註解	功能
`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	捨棄暫存的變更。需分兩個步驟，請參閱確認破壞性操作。
`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 的工具會變更或移除項目，或開始撥打給真人。無法復原的操作需要兩次請求。第一次請求不會變更任何內容，並會傳回：

{
  "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 區塊：

{
  "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 無效請求錯誤。