Kết nối AI bên ngoài (MCP Server)
OmnyBot cung cấp MCP Server tích hợp sẵn tại trang Cài đặt → Quản trị → Kết nối AI (/{slug}/settings/mcp), cho phép các trợ lý và trình soạn thảo AI bên ngoài truy cập an toàn vào Kho tri thức, Bot AI và hội thoại trong Workspace của bạn qua giao thức Model Context Protocol (MCP).
Thông số kết nối & Client hỗ trợ
Phần tiêu đề “Thông số kết nối & Client hỗ trợ”- Endpoint MCP:
https://<ten-mien-cua-ban>/api/mcp - Giao thức vận chuyển: Streamable HTTP ở chế độ stateless, phản hồi JSON (chỉ chấp nhận phương thức
POST;GETvàDELETEtrả về HTTP405 Method Not Allowed). - Hướng dẫn tích hợp sẵn trên giao diện:
- Claude (Web) (OAuth 2.1)
- ChatGPT (OAuth 2.1)
- Claude Code:
claude mcp add --transport http omnybot <endpoint> - Cursor & Antigravity: cấu hình JSON
mcpServers.omnybot.url - Kết nối bằng Token thủ công: gửi header
Authorization: Bearer omny_mcp_...
Xác thực: OAuth 2.1 hoặc Personal Access Token
Phần tiêu đề “Xác thực: OAuth 2.1 hoặc Personal Access Token”OmnyBot hỗ trợ hai phương thức xác thực cho MCP client:
1. OAuth 2.1 (PKCE + Dynamic Client Registration)
Phần tiêu đề “1. OAuth 2.1 (PKCE + Dynamic Client Registration)”Các client hỗ trợ OAuth (như Claude Web, ChatGPT, Claude Code) tự động khám phá metadata qua:
/.well-known/oauth-protected-resource(RFC 9728)/.well-known/oauth-authorization-server(RFC 8414)- Đăng ký client động tại
POST /api/oauth/register(RFC 7591) và cấp token tạiPOST /api/oauth/token.
Khi kết nối, bạn sẽ được chuyển tới trang xác nhận cấp quyền (Consent) của OmnyBot để chọn Workspace và phạm vi (READ hoặc WRITE). Phiên OAuth cấp Access Token có hiệu lực 1 giờ (3600 giây) và Refresh Token dùng một lần (tiền tố omny_mcpr_) có hiệu lực 30 ngày.
2. Personal Access Token (Tạo thủ công)
Phần tiêu đề “2. Personal Access Token (Tạo thủ công)”- Tại Cài đặt → Kết nối AI, nhấn biểu tượng
+ở mục Token truy cập. - Nhập Tên token, chọn phạm vi quyền:
READ: Chỉ hiển thị và cho phép gọi các công cụ đọc dữ liệu.WRITE: Cho phép gọi cả công cụ đọc và công cụ ghi/chỉnh sửa (vẫn tuân thủ quyền công cụ và cơ chế xác nhận).
- Chọn thời hạn hiệu lực: 30 ngày, 90 ngày (mặc định), 365 ngày hoặc Không hết hạn.
- Sao chép ngay chuỗi token (bắt đầu bằng
omny_mcp_).
Công cụ MCP & Phân quyền chi tiết
Phần tiêu đề “Công cụ MCP & Phân quyền chi tiết”MCP Server chia sẻ cùng hệ thống công cụ với Trợ lý Mina (trừ connect_account và manage_bot_tools không hỗ trợ qua MCP) và bổ sung thêm các công cụ thao tác hội thoại trực tiếp:
- Công cụ từ Mina: tra cứu/tạo/sửa/xóa Kho tri thức, quản lý bộ sưu tập, xử lý lỗ hổng tri thức, quản lý/kiểm thử Bot AI, kiểm tra tình trạng kênh (
nick_health), đọc hội thoại chưa đọc, tạo/đổi tên thẻ. - Công cụ hội thoại MCP:
list_conversations,get_conversation_messages,reply_conversation.
Tại mục Công cụ (Tools) trên trang Kết nối AI, bạn có thể thiết lập mức quyền cho từng công cụ (dùng chung với Mina):
| Mức quyền | Hành vi |
|---|---|
always | Cho phép thực thi ngay không cần hỏi lại |
ask (mặc định) | Yêu cầu xác nhận: lần gọi đầu trả về trạng thái needs_confirmation kèm confirm_token; client chỉ gửi lại kèm confirm_token sau khi người dùng đồng ý |
deny | Ẩn hoàn toàn công cụ khỏi danh sách tools/list và từ chối mọi lời gọi |
Giới hạn tốc độ (Rate Limiting)
Phần tiêu đề “Giới hạn tốc độ (Rate Limiting)”Endpoint POST /api/mcp áp dụng giới hạn trượt (sliding window) hai tầng (trả về HTTP 429 Too Many Requests kèm header X-RateLimit-* và Retry-After khi vượt ngưỡng):
- Tầng 1 (theo IP): mặc định 120 yêu cầu / 60 giây.
- Tầng 2 (theo từng Token): mặc định 60 yêu cầu / 60 giây.