---
title: "Sử dụng ThunderPhone làm máy chủ MCP"
description: "Xây dựng, kiểm thử, xác thực và vận hành tác nhân AI giọng nói ThunderPhone từ Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code hoặc một ứng dụng khách MCP HTTP có thể truyền phát khác."
---

ThunderPhone cung cấp máy chủ Model Context Protocol HTTP có thể truyền luồng tại:

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

Đây là hướng ngược lại với [kết nối máy chủ MCP từ xa với tác nhân AI](/vi/guides/mcp-servers):

| Hướng | Kết quả |
| --- | --- |
| Máy chủ MCP từ xa → tác nhân ThunderPhone | Tác nhân AI có thể gọi các công cụ của máy chủ từ xa. |
| ThunderPhone → ứng dụng MCP của bạn | Tác nhân lập trình của bạn có thể xây dựng, kiểm thử và vận hành ThunderPhone. |

## Xác thực

Mặc định, hãy dùng [OAuth](/vi/guides/oauth) cho ứng dụng khách từ danh mục: đăng nhập, chọn một tổ chức và phê duyệt các quyền được yêu cầu. Thu hồi quyền truy cập tại **Tổ chức → Khóa API → Ứng dụng được ủy quyền**.

Với ứng dụng khách được cấu hình bằng khóa API, hãy tạo khóa `sk_live_` tại **Tổ chức → Khóa** và cung cấp khóa đó cho ứng dụng MCP của bạn dưới dạng `THUNDERPHONE_API_KEY`. Khóa được liên kết với một tổ chức; một ID thuộc tổ chức khác sẽ hoạt động như không tìm thấy.

<Warning>
  Khóa `sk_live_` có thể đọc dữ liệu tổ chức và thực hiện các thao tác trong môi trường production như triển khai tác nhân, thực hiện cuộc gọi, mua số, khởi động chiến dịch và xóa tài nguyên. Không đưa khóa này vào mã trình duyệt, kho lưu trữ, ảnh chụp màn hình và nhật ký trò chuyện. Hãy dùng kho bí mật hoặc hỗ trợ biến môi trường của ứng dụng khách, đồng thời thu hồi ngay khóa bị lộ.
</Warning>

## Các lựa chọn thay thế CLI và stdio

[ThunderPhone CLI](/vi/guides/cli) có thể ghi cấu hình ứng dụng khách mà vẫn giữ nguyên
các máy chủ không liên quan:

```bash
npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user
```

Sau khi cài đặt `@thunderphone/mcp` trên toàn hệ thống, hãy dùng `thunderphone-mcp setup` với
các tùy chọn tương tự. Thiết lập hỗ trợ Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop và Windsurf. Ưu tiên HTTP trực tiếp; Desktop sử dụng stdio.

Với bất kỳ ứng dụng khách nào hỗ trợ stdio, hãy cấu hình `command: "npx"` với
`args: ["-y", "@thunderphone/mcp"]`. Trình bao bọc sẽ dùng `THUNDERPHONE_API_KEY` trước,
sau đó là thông tin xác thực từ `thunderphone login`, làm mới token đã hết hạn, rồi dùng
OAuth qua `mcp-remote`. Đăng nhập thiết bị và OAuth yêu cầu API triển khai OAuth tương ứng.
Đường dẫn khóa API thì không. Cấu hình HTTP trực tiếp không đọc kho thông tin xác thực
CLI; hãy dùng trình bao bọc stdio để tái sử dụng đăng nhập thiết bị.

Đây là các lựa chọn thay thế cho cấu hình ứng dụng khách thủ công bên dưới.

## Cấu hình ứng dụng khách

Claude và ChatGPT đăng nhập bằng [OAuth](/vi/guides/oauth); không cần API key. Nếu bạn chưa có tài khoản ThunderPhone, hãy chọn **Tạo tài khoản** trên trang đăng nhập; sau khi xác minh email, bạn sẽ quay lại màn hình phê duyệt.

### Claude (web, máy tính để bàn và di động)

1. Mở **Tùy chỉnh → Trình kết nối** (**Cài đặt → Trình kết nối** trong các phiên bản cũ hơn). Nếu ThunderPhone xuất hiện trong danh mục trình kết nối, hãy chọn nó. Nếu không, hãy chọn **Thêm trình kết nối tùy chỉnh**, đặt tên là `ThunderPhone`, rồi nhập `https://api.thunderphone.com/v1/mcp`.
2. Chọn **Kết nối**, đăng nhập vào ThunderPhone, chọn tổ chức và phê duyệt quyền.
3. Trong cuộc trò chuyện, bật ThunderPhone từ menu công cụ và yêu cầu nội dung bạn cần, ví dụ: "Liệt kê các tác nhân AI của tôi".

Claude sẽ hỏi trước khi sử dụng từng công cụ lần đầu. Để bỏ qua hầu hết các lời nhắc đó, hãy mở **Tùy chỉnh → Trình kết nối → ThunderPhone** và đặt **Công cụ chỉ đọc** thành luôn cho phép. Các công cụ này chỉ tra cứu: tác nhân AI, cuộc gọi, bản chép lời, số dư, tài liệu. Giữ **Công cụ ghi/xóa** ở chế độ phê duyệt nếu bạn muốn xem từng thay đổi trước khi diễn ra.

Trình kết nối tùy chỉnh yêu cầu gói Claude trả phí. Với gói Team và Enterprise, chủ sở hữu cần thêm trình kết nối trong phần cài đặt trình kết nối của tổ chức trước, sau đó mỗi thành viên sẽ kết nối tài khoản ThunderPhone riêng của mình.

### ChatGPT

1. Nếu ThunderPhone xuất hiện trong danh mục ứng dụng ChatGPT, hãy chọn và kết nối.
2. Nếu không, hãy mở **Cài đặt → Ứng dụng & Trình kết nối → Cài đặt nâng cao**, bật **Chế độ nhà phát triển**, rồi tạo trình kết nối với URL `https://api.thunderphone.com/v1/mcp` và xác thực OAuth.
3. Đăng nhập vào ThunderPhone, chọn tổ chức và phê duyệt quyền. Thêm ThunderPhone vào cuộc trò chuyện từ menu công cụ.

Việc xóa tác nhân AI hoặc số điện thoại, hủy bản nháp, khởi chạy chiến dịch và gửi yêu cầu kiểm thử có thể ghi vào hệ thống bên ngoài đều yêu cầu xác nhận lần hai trong cả hai ứng dụng; xem [Xác nhận các thao tác phá hủy](#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

Thêm nội dung này vào `~/.codex/config.toml`:

```toml
[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"
```

### Cursor

Tạo `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Thêm cầu nối `mcp-remote` vào cấu hình 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

Tạo `.vscode/mcp.json` và nhập key thông qua lời nhắc nhập của 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}"
      }
    }
  }
}
```

## Công cụ

Mỗi công cụ đều có chú thích MCP. Trong các bảng, **R** nghĩa là chỉ đọc, **D** là phá hủy, **I** là lũy đẳng và **O** là tương tác với thế giới mở/mạng. Dấu gạch ngang nghĩa là không có gợi ý nào được đặt.

### Kết nối

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Xác thực thông tin xác thực và trả về tổ chức cùng siêu dữ liệu thông tin xác thực an toàn. |

### Tác nhân AI

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Liệt kê tác nhân AI. |
| `get_agent` | `agent_id` | R, I | Lấy một tác nhân AI. |
| `create_agent` | cấu hình tác nhân AI | — | Tạo một tác nhân AI. |
| `update_agent` | `agent_id`, các trường đã thay đổi | D | Đưa các trường vào bản nháp tác nhân AI, thay thế nội dung hiện có trong bản nháp. Chạy mà không cần bước xác nhận: tác nhân AI đã triển khai không thay đổi cho đến khi `deploy_agent` được gọi, và `discard_agent_draft` hoàn nguyên bản nháp. |
| `deploy_agent` | `agent_id`, `if_updated_at` tùy chọn | D, I | Đưa bản nháp vào môi trường production. |
| `discard_agent_draft` | `agent_id`, `if_updated_at` tùy chọn, `confirmation_token` ở yêu cầu thứ hai | D, I | Hủy các thay đổi đã đưa vào bản nháp. Gồm hai bước, xem [Xác nhận thao tác phá hủy](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, `name` tùy chọn | — | Sao chép một tác nhân AI trong tổ chức. |
| `delete_agent` | `agent_id`, `confirmation_token` ở yêu cầu thứ hai | D, I | Xóa vĩnh viễn một tác nhân AI. Gồm hai bước. |
| `list_agent_versions` | `agent_id` | R, I | Liệt kê các phiên bản cấu hình đã triển khai. |

### Số điện thoại và nhà cung cấp viễn thông

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Liệt kê số của tổ chức và định tuyến. |
| `get_phone_number_limits` | — | R, I | Lấy mức sử dụng và giới hạn của số được quản lý. |
| `provision_phone_number` | tùy chọn `area_code`, `city`, `state`, `idempotency_key` | D, O | Mua số gọi đến do ThunderPhone quản lý. |
| `list_voip_connections` | — | R, I | Liệt kê nhà mạng của khách hàng đã kết nối. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, tùy chọn `area_code` | R, I, O | Tìm kiếm kho số của nhà mạng. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Nhập các số đã sở hữu tại nhà mạng. |
| `update_phone_number` | `phone_number_id`, các trường định tuyến/nhãn/webhook | D | Cập nhật định tuyến số, bao gồm cả việc gán tác nhân AI. |
| `delete_phone_number` | `phone_number_id`, `confirm`, tùy chọn `release_at_provider`, `confirmation_token` trong yêu cầu thứ hai | D, I, O | Giải phóng một số. Gồm hai bước. |

### SMS

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Gửi một SMS văn bản thuần túy qua số Twilio hoặc Telnyx đã kết nối. |

### Cuộc gọi

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_calls` | bộ lọc tùy chọn, `limit`, `offset` | R, I | Liệt kê cuộc gọi với các bộ lọc lịch sử cuộc gọi REST. |
| `get_call` | `call_id` | R, I | Lấy trạng thái cuộc gọi và siêu dữ liệu. |
| `get_call_transcript` | `call_id`, `live` tùy chọn | R, I | Lấy bản chép lời cuộc gọi. |
| `get_call_audio_url` | `call_id`, `download` tùy chọn | R, I, O | Trả về URL âm thanh đã ký; không bao giờ truyền trực tuyến âm thanh qua MCP. |
| `get_call_grade` | `call_id` | R, I | Lấy điểm đánh giá cuộc gọi mới nhất. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Thực hiện một cuộc gọi đi không có tính idempotent. |
| `export_calls` | bộ lọc cuộc gọi, `export_format` | R, I | Xuất tối đa đến giới hạn của endpoint REST dưới dạng JSON hoặc CSV. |

### Kiểm thử và xác thực

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Liệt kê các kịch bản kiểm thử. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, điều kiện tùy chọn | — | Tạo một kịch bản. |
| `generate_test_scenarios` | `agent_id`, `count` tùy chọn, `include_edge_cases`, `locale` | O | Tạo các kịch bản từ prompt của tác nhân AI. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, lựa chọn/ma trận tùy chọn | D, O | Chạy các kịch bản qua web hoặc điện thoại. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Lấy trạng thái lô và kết quả theo từng kịch bản. |
| `list_validation_runs` | `agent_id` | R, I | Liệt kê các lần chạy xác thực bản nháp gần đây. |
| `get_validation_status` | `agent_id` | R, I | Lấy trạng thái xác thực mới nhất và kết quả khớp bản nháp. |

### Kiến thức

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Liệt kê cơ sở kiến thức. |
| `create_knowledge_base` | `name`, `description` tùy chọn | — | Tạo một cơ sở kiến thức. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Thêm văn bản hoặc Markdown. |
| `import_knowledge_url` | `url`, `name` tùy chọn | O | Đưa một trang công khai vào hàng đợi để thu thập an toàn. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Tìm kiếm thông qua truy xuất trong môi trường vận hành. |

### Tích hợp, webhook và máy chủ MCP từ xa

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Liệt kê các tích hợp hàm HTTP. |
| `create_integration` | `display_name`, `spec` hàm, các trường endpoint tùy chọn | — | Tạo công cụ HTTP. Thêm header xác thực trong bảng điều khiển. |
| `test_integration` | `url`, phương thức/nội dung/thời gian chờ tùy chọn, `integration_id` kèm `header_names`, `confirmation_token` trong yêu cầu thứ hai | D, O | Gửi yêu cầu kiểm thử có giới hạn và được bảo vệ khỏi SSRF. Các giá trị header đã lưu được điền từ tích hợp và chỉ gửi đến máy chủ của chính tích hợp đó. `POST` (mặc định), `PUT`, `PATCH` và `DELETE` gồm hai bước; `GET` chạy ngay. |
| `list_webhook_endpoints` | — | R, I | Liệt kê các endpoint webhook đã ký. |
| `list_webhook_deliveries` | `agent_id` tùy chọn, `endpoint_id` tùy chọn | R, I | Liệt kê các kết quả gửi webhook gần đây không kèm payload. |
| `create_webhook_endpoint` | `label`, `url`, sự kiện/trạng thái tùy chọn | O | Tạo endpoint webhook đã ký. |
| `test_webhook_endpoint` | `endpoint_id` | O | Gửi sự kiện tổng hợp thông qua quy trình gửi thông thường. |
| `list_mcp_servers` | — | R, I | Liệt kê các máy chủ từ xa mà tác nhân AI giọng nói có thể gọi. |
| `create_mcp_server` | `display_name`, `url` | O | Đăng ký và đồng bộ máy chủ từ xa. Các máy chủ cần header xác thực được thêm trong bảng điều khiển. |
| `sync_mcp_server_tools` | `server_id` | D, O | Làm mới danh mục công cụ của máy chủ từ xa. |

### Chiến dịch

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Liệt kê chiến dịch gọi ra. |
| `create_campaign` | trường chiến dịch | — | Tạo một chiến dịch bản nháp. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Thêm tối đa 5.000 liên hệ JSON. |
| `campaign_action` | `campaign_id`, `action`, `consent_to_charge` tùy chọn, `confirmation_token` trong yêu cầu thứ hai | D, O | Chạy `start`, `pause`, `resume` hoặc `stop`. `start` và `resume` gồm hai bước; `pause` và `stop` chạy ngay lập tức. |
| `get_campaign_stats` | `campaign_id` | R, I | Lấy bộ đếm và kết quả gần đây. |

### Giọng nói, thanh toán và tài liệu

| Công cụ | Đối số chính | Chú thích | Chức năng |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Liệt kê giọng nói và ngôn ngữ được hỗ trợ. |
| `preview_voice` | `voice`, `language`, `text` | O | Tạo mẫu và trả về URL đã ký. |
| `list_voice_clones` | — | R, I | Liệt kê các bản sao giọng nói tùy chỉnh. |
| `get_billing_summary` | — | R, I | Lấy số dư và giá bậc chính thức; không cung cấp thao tác thay đổi thanh toán. |
| `search_docs` | `query`, `limit` tùy chọn | R, I, O | Tìm kiếm trong chỉ mục tài liệu công khai. |
| `get_doc_page` | `path` | R, I, O | Lấy một trang tài liệu Markdown công khai. |

Mọi công cụ sản phẩm đều sử dụng cùng đường dẫn mã REST như API công khai. Vì vậy, xác thực REST, phạm vi tổ chức, vai trò, điều kiện thanh toán, hạn ngạch, xác nhận TCPA, an toàn nhà cung cấp và hành vi kiểm toán được áp dụng không thay đổi.

## Xác nhận hành động phá hủy

Các công cụ được đánh dấu D sẽ thay đổi hoặc xóa một thứ gì đó, hoặc bắt đầu gọi cho người thật. Những thao tác không thể hoàn tác cần hai yêu cầu. Yêu cầu đầu tiên không thay đổi gì và trả về:

```json
{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}
```

Tác nhân AI cho người dùng biết nội dung nào bị ảnh hưởng và yêu cầu xác nhận. Sau đó, tác nhân AI lặp lại yêu cầu với cùng đối số cùng với `confirmation_token`. Token có hiệu lực trong 10 phút và áp dụng cho một tổ chức, một công cụ và một tập đối số chính xác, vì vậy việc xóa ba tác nhân AI cần ba lần xác nhận. `campaign_action` với `pause` hoặc `stop` bỏ qua bước này để một chiến dịch đang chạy luôn có thể được dừng ngay lập tức; `test_integration` với `GET` cũng vậy. Một số công cụ D chạy trong một yêu cầu vì ký hiệu D đánh dấu tác động của chúng, không phải xác nhận phía máy chủ: `update_agent` thay thế nội dung bản nháp đang có (`discard_agent_draft` hoàn tác thay đổi này), `deploy_agent` thay thế cấu hình đang hoạt động, `update_phone_number` định tuyến lại các cuộc gọi đang hoạt động, `sync_mcp_server_tools` thay thế danh mục công cụ của máy chủ từ xa, `import_voip_numbers` chuyển lại số về nhà cung cấp dịch vụ của bạn, `run_agent_tests` có thể tiêu tốn credit, `send_sms` và `place_call` liên hệ với người thật (`place_call` vẫn giữ xác nhận đồng ý riêng), và `provision_phone_number` mua một số. Ứng dụng MCP của bạn vẫn có thể yêu cầu bạn phê duyệt các thao tác này.

## Prompt khởi đầu

`prompts/list` cung cấp năm quy trình làm việc có thể tái sử dụng:

- `create_inbound_receptionist`
- `run_agent_tests`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`

Dùng `prompts/get` với tên prompt được liệt kê và các đối số đã khai báo để nhận tin nhắn người dùng sẵn sàng chạy.

## Tài nguyên

`resources/list` hiển thị các tham chiếu công khai được lưu vào bộ nhớ đệm:

| URI | Nội dung |
| --- | --- |
| `thunderphone://docs/llms.txt` | Chỉ mục tài liệu công khai. |
| `thunderphone://docs/quickstart` | Markdown hướng dẫn nhanh. |
| `thunderphone://pricing` | Markdown về giá công khai hiện tại. |

Đọc một tài nguyên bằng `resources/read`. Các lượt truy xuất công khai dùng thời gian chờ ngắn, giới hạn 2 MiB và bộ nhớ đệm trong tiến trình trong mười phút.

## Giao thức và lỗi

Máy chủ hỗ trợ các phiên bản giao thức `2025-06-18` và `2025-03-26`; máy chủ phản hồi lại phiên bản ứng dụng khách được hỗ trợ và nếu không thì chọn `2025-06-18`. Máy chủ triển khai `initialize`, `ping`, công cụ, prompt, tài nguyên và thông báo. Thông báo trả về `202 Accepted`. Máy chủ không trạng thái này không cung cấp trình lắng nghe SSE hoặc chức năng xóa phiên, vì vậy `GET` và `DELETE` trả về `405 Method Not Allowed` với `Allow: POST`.

Lỗi công cụ vẫn là phản hồi JSON-RPC thành công với `isError: true`. Nội dung của chúng chứa một câu ngắn, theo sau là một khối 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."
}
```

Tiền tố riêng biệt `outbound_tcpa_confirmation_required:` được giữ lại cho `place_call`. Các phương thức JSON-RPC không xác định trả về `-32601` trong phản hồi HTTP `200`. MCP `2025-06-18` không hỗ trợ batch JSON-RPC và trả về lỗi yêu cầu không hợp lệ `-32600` rõ ràng.