Open in

将 ThunderPhone 用作 MCP 服务器

通过 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他 Streamable HTTP MCP 客户端构建、测试、验证和运营 ThunderPhone 语音智能体。

ThunderPhone 在以下地址提供 Streamable 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 客户端。该密钥绑定到一个组织；属于其他组织的 ID 会被视为未找到。

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 在首次使用每个工具前都会请求确认。如需跳过大多数此类提示，请打开 自定义 → 连接器 → 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 号码发送一条纯文本短信。

通话

工具	主要参数	注释	功能说明
`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 会返回带有 Allow: POST 的 405 Method Not Allowed。

工具失败仍会以成功的 JSON-RPC 响应返回，并带有 isError: true。其文本包含一句简短说明，后跟一个 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 无效请求错误。