Bỏ qua để đến nội dung

Kết nối AI bên ngoài (MCP Server)

Xem dạng Markdown

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

  • 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; GET và DELETE trả về HTTP 405 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:

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ại POST /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.

  1. Tại Cài đặt → Kết nối AI, nhấn biểu tượng + ở mục Token truy cập.
  2. 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).
  3. 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.
  4. Sao chép ngay chuỗi token (bắt đầu bằng omny_mcp_).

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ềnHành vi
alwaysCho 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

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.