Telerivet MCP

npx add-mcp 'https://api.telerivet.com/mcp'

Telerivet cung cấp máy chủ Model Context Protocol (MCP), cho phép các tác nhân AI và công cụ dựa trên LLM như Claude và ChatGPT tương tác với REST API của Telerivet bằng giao diện MCP tiêu chuẩn.

Máy chủ MCP của Telerivet cho phép các tác nhân AI thực hiện nhiều thao tác trong Telerivet, bao gồm gửi và lên lịch gửi tin nhắn, truy xuất dữ liệu và thống kê mức sử dụng, nhập danh bạ, cũng như cấu hình dự án, tuyến và dịch vụ tự động.

Điểm cuối MCP có tại:

https://api.telerivet.com/mcp

Các ứng dụng MCP kết nối qua phương thức truyền tải Streamable HTTP, sử dụng thông điệp JSON-RPC 2.0 qua các yêu cầu HTTP POST.

Cấu hình ứng dụng

Điểm cuối MCP yêu cầu xác thực qua OAuth 2.0.

Các ứng dụng MCP hỗ trợ OAuth Client ID Metadata Documents (CIMD) có thể kết nối mà không cần cấu hình thủ công: Telerivet tự động đăng ký ứng dụng lần đầu tiên người dùng cấp quyền cho ứng dụng đó. Telerivet không hỗ trợ Dynamic Client Registration.

Hướng dẫn thiết lập dành cho các ứng dụng MCP sau:

• Claude (claude.ai và Claude Desktop)
• Claude Code
• ChatGPT
• Codex
• Antigravity CLI
• Hermes Agent

Đối với các ứng dụng MCP không hỗ trợ Client ID Metadata Documents, cần cấu hình OAuth Client thủ công. Để sử dụng một ứng dụng MCP khác không hỗ trợ CIMD, bạn có thể thêm OAuth Client mới trong tổ chức Telerivet của mình và cấu hình các URL callback OAuth mà ứng dụng MCP yêu cầu. (Dịch vụ cung cấp ứng dụng MCP có thể nêu các URL callback OAuth trong tài liệu của họ.) Khi OAuth Client được cấu hình thủ công theo cách này, chỉ người dùng trong tổ chức Telerivet của bạn mới có thể truy cập ứng dụng đó.

Cấp quyền cho ứng dụng MCP

Khi kết nối một ứng dụng MCP, ứng dụng sẽ chuyển hướng bạn đến Telerivet để cấp quyền truy cập. Trên trang này, bạn chọn:

• Quyền – loại dữ liệu và thao tác mà ứng dụng có thể truy cập (ví dụ: Xem tin nhắn, Gửi tin nhắn hoặc Chỉnh sửa dịch vụ tự động). Bỏ chọn mọi quyền mà bạn không muốn cấp cho ứng dụng. Ứng dụng không bao giờ có thể thực hiện nhiều hơn những gì tài khoản người dùng của bạn được phép làm; các phương thức API yêu cầu quyền mà bạn không cấp sẽ bị ẩn khỏi ứng dụng MCP.
• Tổ chức – tổ chức mà ứng dụng có thể truy cập. Mỗi lần cấp quyền chỉ áp dụng cho một tổ chức; để sử dụng ứng dụng với tổ chức khác, hãy kết nối lại ứng dụng.

Phê duyệt ứng dụng cho tổ chức của bạn. Mỗi ứng dụng MCP (chẳng hạn như Claude hoặc ChatGPT) phải được quản trị viên tổ chức phê duyệt trước khi có thể sử dụng trong tổ chức. Nếu bạn là quản trị viên tổ chức, trang cấp quyền cho phép bạn phê duyệt ứng dụng cho tổ chức và chọn Ai có thể sử dụng ứng dụng này?: tất cả người dùng trong tổ chức, chỉ quản trị viên tổ chức, hoặc quản trị viên tổ chức và quản trị viên dự án. Những người dùng khác sẽ thấy thông báo yêu cầu họ liên hệ với quản trị viên tổ chức để phê duyệt ứng dụng.

Thu hồi quyền truy cập. Bạn có thể thu hồi quyền truy cập của ứng dụng vào tài khoản của mình bất cứ lúc nào trong mục Ứng dụng được cấp quyền của phần cài đặt Bảo mật tài khoản. Quản trị viên tổ chức có thể xem xét và thu hồi mã truy cập của mọi người dùng trên trang Mã truy cập OAuth, hoặc thu hồi hoàn toàn một ứng dụng trên trang Ứng dụng đã kết nối.

Kiểm soát của tổ chức

Quản trị viên tổ chức có thể kiểm soát những gì mỗi ứng dụng MCP đã được phê duyệt được phép thực hiện trong tổ chức trên trang Ứng dụng đã kết nối (cũng được liên kết từ trang Developer API của tổ chức). Nhấp vào một ứng dụng để xem hoặc thay đổi cài đặt. Các cài đặt này áp dụng cho quyền truy cập của mọi người dùng vào ứng dụng đó trong tổ chức, bất kể người dùng đã cấp những quyền nào khi kết nối ứng dụng.

Quyền bắt buộc – những người dùng nào trong tổ chức có thể cấp quyền cho ứng dụng (tất cả người dùng, chỉ quản trị viên tổ chức, hoặc quản trị viên tổ chức và quản trị viên dự án).

Thao tác được phép – với mỗi loại thao tác, ứng dụng có thể tự thực hiện hay người dùng phải phê duyệt từng thao tác, hoặc thao tác đó hoàn toàn không được phép:

Thao tác	Mô tả	Tùy chọn	Mặc định
Đọc dữ liệu	Tra cứu danh bạ, tin nhắn, số liệu thống kê và dữ liệu dự án khác.	Được phép, Không được phép	Được phép
Tạo và cập nhật dữ liệu	Tạo và chỉnh sửa danh bạ, nhóm, dịch vụ, chiến dịch nháp, tuyến và dữ liệu dự án khác.	Được phép, Yêu cầu phê duyệt, Không được phép	Được phép
Gửi tin nhắn và kích hoạt dịch vụ	Gửi hoặc lên lịch gửi tin nhắn và cuộc gọi đến danh bạ, kích hoạt dịch vụ tự động và chạy tập lệnh.	Được phép, Yêu cầu phê duyệt, Không được phép	Yêu cầu phê duyệt
Xóa dữ liệu	Xóa danh bạ, tin nhắn, dịch vụ và dữ liệu dự án khác.	Được phép, Yêu cầu phê duyệt, Không được phép	Yêu cầu phê duyệt
Gửi yêu cầu web bên ngoài	Gửi yêu cầu đến các trang web bên ngoài và API của bên thứ ba từ tập lệnh do ứng dụng này chạy.	Được phép, Không được phép	Được phép

Khi một loại thao tác được đặt thành Không được phép, công cụ MCP tương ứng (chẳng hạn như send_api hoặc delete_api) sẽ bị ẩn khỏi ứng dụng MCP và mọi yêu cầu API thuộc loại đó đều bị từ chối. Công cụ run_script tuân theo cài đặt nghiêm ngặt nhất trong các loại gửi, tạo/cập nhật và xóa dữ liệu.

Một số ứng dụng quy định giá trị mặc định riêng – ví dụ: một tác nhân tự động cần gửi tin nhắn khi không có người dùng. Khi giá trị mặc định của ứng dụng khác với giá trị mặc định tiêu chuẩn, trang Ứng dụng đã kết nối sẽ ghi chú giá trị mặc định của ứng dụng bên cạnh cài đặt. Cài đặt của tổ chức bạn luôn được ưu tiên.

Quyền được phép – loại dữ liệu và thao tác mà ứng dụng có thể truy cập trong tổ chức này. Bỏ chọn một quyền sẽ chặn các thao tác API tương ứng đối với tất cả người dùng của ứng dụng trong tổ chức, ngay cả khi người dùng đã cấp quyền đó khi kết nối ứng dụng.

Thu hồi quyền truy cập – xóa ứng dụng khỏi danh sách ứng dụng được tổ chức phê duyệt và thu hồi tất cả mã truy cập hiện có của ứng dụng trong tổ chức.

Các ứng dụng thuộc sở hữu của chính tổ chức bạn (được thêm qua Thêm OAuth Client) không cần phê duyệt; các thao tác được phép của chúng được cấu hình trên trang cài đặt riêng của ứng dụng.

Xác nhận có người tham gia

Khi một loại thao tác được đặt thành Yêu cầu phê duyệt trên trang Ứng dụng đã kết nối, ứng dụng MCP không thể thực hiện các thao tác đó cho đến khi người dùng phê duyệt rõ ràng từng thao tác. Theo mặc định, điều này áp dụng cho việc gửi tin nhắn và kích hoạt dịch vụ, cũng như xóa dữ liệu.

Các thao tác thuộc loại gửi bao gồm gửi hoặc lên lịch gửi tin nhắn và cuộc gọi, gửi lại tin nhắn, kích hoạt dịch vụ tự động, tạo tác vụ hàng loạt, mô phỏng tin nhắn đến, chỉnh sửa tin nhắn hoặc chiến dịch đã lên lịch, kích hoạt dịch vụ tự động hoặc thay đổi cấu hình của dịch vụ đang hoạt động, tạo webhook hoặc thay đổi URL webhook, thay đổi số điện thoại hoặc cài đặt nhà cung cấp của tuyến, thay đổi tuyến mặc định của dự án và chạy tập lệnh bằng công cụ run_script. Loại xóa bao gồm tất cả phương thức xóa, cũng như giảm thời gian lưu giữ tin nhắn của dự án.

Tùy thuộc vào ứng dụng MCP, bạn có thể phê duyệt thao tác theo một trong các cách sau:

Lời nhắc phê duyệt trong ứng dụng MCP

Nếu ứng dụng MCP hỗ trợ MCP elicitation (sử dụng phiên bản giao thức MCP 2026-07-28 trở lên), ứng dụng MCP sẽ nhắc bạn phê duyệt thao tác ngay trong ứng dụng, kèm mô tả bằng ngôn ngữ thông thường về việc thao tác sẽ thực hiện và dự án bị ảnh hưởng. Nếu bạn phê duyệt, thao tác sẽ được thực hiện ngay. Nếu bạn từ chối, thao tác sẽ không được thực hiện và mô hình AI sẽ được yêu cầu không thử lại.

Bản nháp tin nhắn

Nếu ứng dụng MCP hỗ trợ tiện ích mở rộng MCP Apps, mô hình AI có thể dùng công cụ draft_message để hiển thị bản nháp tin nhắn văn bản có thể chỉnh sửa, bao gồm cả người nhận. Nhấp Gửi để phê duyệt việc gửi chính xác tin nhắn đó đến những người nhận đó.

Liên kết phê duyệt

Nếu ứng dụng MCP không hỗ trợ các cách trên hoặc không thể phê duyệt thao tác theo những cách đó, mô hình AI sẽ nhận được liên kết đến trang Phê duyệt thao tác trong ứng dụng web Telerivet và nên yêu cầu bạn mở trang này. Trang hiển thị ứng dụng, dự án, mô tả thao tác và toàn bộ chi tiết yêu cầu. Sau khi nhấp Phê duyệt, hãy quay lại ứng dụng MCP và yêu cầu ứng dụng thử lại.

Để phê duyệt một thao tác, bạn phải có quyền mà chính thao tác đó yêu cầu (ví dụ: quyền gửi tin nhắn trong dự án). Việc phê duyệt thao tác không cấp thêm quyền nào cho ứng dụng.

Cách thức phê duyệt

• Mỗi lần phê duyệt chỉ áp dụng cho một yêu cầu chính xác – cùng phương thức API với cùng tham số – và chỉ có thể sử dụng một lần. Nếu mô hình AI thay đổi bất kỳ chi tiết nào của yêu cầu, yêu cầu đó phải được phê duyệt lại.
• Phê duyệt hết hạn sau 1 giờ.
• Các yêu cầu API do tập lệnh thực hiện mà bạn đã phê duyệt qua run_script không cần được phê duyệt riêng.
• Nếu ứng dụng gọi trực tiếp REST API bằng mã truy cập của ứng dụng (thay vì qua MCP), các yêu cầu cần phê duyệt sẽ thất bại với mã lỗi confirmation_required, và thông báo lỗi sẽ bao gồm liên kết phê duyệt. Để thực hiện các thao tác này khi không có người dùng, chẳng hạn như trong tích hợp phía máy chủ hoặc tác nhân tự động, quản trị viên tổ chức cần đặt loại thao tác thành Được phép.

Duyệt tin nhắn. Ngoài các quy định trên, nếu dự án bật Duyệt tin nhắn trong Cài đặt nhắn tin, các tin nhắn gửi qua API (bao gồm cả qua MCP) vượt quá giới hạn đã cấu hình sẽ được giữ ở trạng thái chờ cho đến khi người duyệt phê duyệt, giống như tin nhắn gửi từ ứng dụng web.

Công cụ

Máy chủ MCP hiện cung cấp các công cụ sau:

• list_api_methods – Liệt kê các phương thức API hiện có cùng tên, mô tả và tóm tắt tham số. Hỗ trợ lọc theo danh mục.
• get_method_schema – Trả về lược đồ tham số đầy đủ và mô tả các trường phản hồi cho một phương thức API cụ thể.
• read_api – Thực thi phương thức API chỉ đọc để truy xuất dữ liệu.
• modify_api – Thực thi phương thức API tạo hoặc cập nhật dữ liệu.
• delete_api – Thực thi phương thức API xóa dữ liệu.
• send_api – Thực thi phương thức API gửi, lên lịch hoặc nhận tin nhắn, gọi các dịch vụ tự động hoặc thực hiện tác vụ hàng loạt.
• run_analysis_script – Chạy JavaScript chỉ đọc trong môi trường hộp cát Cloud Script API của Telerivet để phân tích dữ liệu dự án – hữu ích cho việc tổng hợp, kết hợp dữ liệu giữa các loại thực thể hoặc quét nhiều bản ghi mà không cần phân trang tất cả qua mô hình. Quyền truy cập API chỉ ở chế độ đọc và HTTP gửi đi bị vô hiệu hóa.
• run_script – Chạy JavaScript có quyền truy cập Cloud Script API (đọc, ghi, gửi, yêu cầu HTTP), dành cho các thao tác hàng loạt mà nếu không sẽ cần nhiều lệnh gọi API riêng lẻ. Các yêu cầu API do tập lệnh thực hiện được kiểm tra theo phạm vi của mã thông báo OAuth, vì vậy tập lệnh không thể thực hiện nhiều hơn những gì mã thông báo đã chạy nó cho phép.
• get_web_app_urls – Trả về thông tin về chức năng ứng dụng web và các mẫu URL. Cho phép tác nhân AI tạo liên kết đến những chức năng không có sẵn trực tiếp qua API. Nếu không có truy vấn, công cụ trả về chỉ mục rút gọn của tất cả các trang; tìm kiếm theo từ khóa hoặc đường dẫn URL sẽ trả về thông tin chi tiết đầy đủ về các trang phù hợp.
• draft_message – Soạn tin nhắn văn bản đơn giản gửi đến một hoặc nhiều số điện thoại (hoặc một nhóm liên hệ) và yêu cầu người dùng phê duyệt trước khi gửi (xem Bản nháp tin nhắn). Chỉ khả dụng nếu ứng dụng MCP hỗ trợ tiện ích mở rộng MCP Apps.
• get_route_options – Trả về thông tin về các tùy chọn tuyến/kênh nhắn tin hiện có. Lọc theo quốc gia, loại kênh hoặc trường hợp sử dụng (hoặc tra cứu một loại tuyến cụ thể) sẽ trả về thông tin chi tiết đầy đủ, bao gồm phạm vi khả dụng theo khu vực địa lý, yêu cầu tuân thủ, quy trình đăng ký, phương thức tính phí (do nội bộ/Telerivet quản lý so với bên ngoài/BYOC), thời gian thiết lập và giá.
• skillbook_search / skillbook_get – Trả về thông tin về các mẫu giải pháp phổ biến, dịch vụ, loại chiến dịch, tính năng nền tảng và mẫu tin nhắn phù hợp với ý định hoặc trường hợp sử dụng.
• search_documentation / get_documentation – Tìm kiếm và truy xuất các mục trong kho tài liệu của Telerivet, bao gồm bài viết trợ giúp trong Hướng dẫn sử dụng, trang pháp lý/chính sách, tài liệu API dành cho nhà phát triển và nội dung tiếp thị/giới thiệu công ty trên www.telerivet.com.

Các công cụ và phương thức API do máy chủ MCP cung cấp có thể thay đổi theo thời gian.

Các liên kết bên dưới hiển thị JSON do máy chủ MCP trả về, có thể giúp bạn hiểu các công cụ và phương thức API hiện có:

• Định nghĩa công cụ
• Kết quả của công cụ list_api_methods
• Kết quả của công cụ get_method_schema cho phương thức Project_queryContacts (thay thành phần cuối cùng của URL để xem lược đồ của các phương thức API khác)
• Kết quả của công cụ get_documentation cho tài liệu tham khảo Cloud Script API (thay thành phần cuối cùng của URL để xem các mục tài liệu khác)

Các phạm vi được cấp cho mã thông báo OAuth của bạn, cùng với các quyền kiểm soát của tổ chức đối với ứng dụng, quyết định những công cụ và phương thức API nào khả dụng. Các phương thức yêu cầu phạm vi mà mã thông báo của bạn không có, hoặc không được tổ chức cho phép đối với ứng dụng, sẽ bị loại khỏi danh sách.