---
title: "将 ThunderPhone 用作 MCP 服务器"
description: "通过 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他 Streamable HTTP MCP 客户端构建、测试、验证和运营 ThunderPhone 语音智能体。"
---

ThunderPhone 在以下地址提供 Streamable HTTP Model Context Protocol 服务器：

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

这与[将远程 MCP 服务器连接到语音智能体](/zh/guides/mcp-servers)的方向相反：

| 方向 | 结果 |
| --- | --- |
| 远程 MCP 服务器 → ThunderPhone 智能体 | 语音智能体可以调用远程服务器的工具。 |
| ThunderPhone → 您的 MCP 客户端 | 您的编程智能体可以构建、测试和操作 ThunderPhone。 |

## 身份验证

对于目录客户端，默认使用 [OAuth](/zh/guides/oauth)：登录、选择组织并批准请求的权限。在**组织 → API 密钥 → 已授权应用**下撤销访问权限。

对于配置了 API 密钥的客户端，请在**组织 → 密钥**下创建 `sk_live_` 密钥，并将其作为 `THUNDERPHONE_API_KEY` 提供给您的 MCP 客户端。该密钥绑定到一个组织；属于其他组织的 ID 会被视为未找到。

<Warning>
  `sk_live_` 密钥可以读取组织数据并执行生产操作，例如部署智能体、发起通话、购买号码、启动营销活动和删除资源。请勿将其放入浏览器代码、代码仓库、截图和聊天记录中。请使用客户端的密钥存储或环境变量支持，并立即撤销已泄露的密钥。
</Warning>

## CLI 和 stdio 替代方案

[ThunderPhone CLI](/zh/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](/zh/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 号码发送一条纯文本短信。 |

### 通话

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

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