Open in

Sử dụng ThunderPhone làm máy chủ MCP

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:

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:

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 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.

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

ThunderPhone 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:

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; 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)

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.
Chọn Kết nối, đăng nhập vào ThunderPhone, chọn tổ chức và phê duyệt quyền.
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

Nếu ThunderPhone xuất hiện trong danh mục ứng dụng ChatGPT, hãy chọn và kết nối.
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.
Đă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.

Claude Code

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:

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

Cursor

Tạo .cursor/mcp.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:

{
  "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:

{
  "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.
`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ề:

{
  "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:

{
  "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.