Open in

將 ThunderPhone 用作 MCP 伺服器

透過 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他支援串流 HTTP 的 MCP 用戶端，建立、測試、驗證及營運 ThunderPhone 語音智能體。

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

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；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（網頁版、桌面版及流動版）

開啟 設定 → 連接器。如 ThunderPhone 出現在連接器目錄中，請選擇它。否則，選擇 新增自訂連接器，命名為 ThunderPhone，並輸入 https://api.thunderphone.com/v1/mcp。
選擇連接，登入 ThunderPhone，選取組織，然後批准權限。
在對話中，從工具選單啟用 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

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

智能體

工具	主要參數	註釋	功能
`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	捨棄已暫存的變更。分兩步進行，請參閱確認破壞性操作。
`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 的工具會變更或移除無法還原的內容，或開始致電真人。這些工具需要兩次請求。第一次請求不會作出任何變更，並會回傳：

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

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