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

:::note[Quyền truy cập]
Trang **Kết nối AI** hiển thị trong mục **Cấu hình → AI Connections** hoặc **Cài đặt → Kết nối AI**. Để quản lý token và phân quyền công cụ trên giao diện trang này, tài khoản cần có quyền **`workspace:manage`** (API backend chấp nhận `ai:manage` hoặc `workspace:manage`).
:::

## 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`**; `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

OmnyBot hỗ trợ hai phương thức xác thực cho MCP client:

### 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ạ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**.

### 2. Personal Access Token (Tạo thủ công)

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_`**).

:::caution[Bảo mật & Thu hồi Token]
Chuỗi token chỉ hiển thị **duy nhất một lần** khi tạo; máy chủ chỉ lưu mã băm **SHA-256**. Mỗi token kế thừa trực tiếp quyền thành viên của người tạo và được kiểm tra lại trên từng yêu cầu — nếu thành viên bị gỡ khỏi Workspace hoặc bị giảm quyền, token tự động mất hiệu lực tương ứng. Mọi thao tác tạo/thu hồi token đều được ghi nhận trong **Nhật ký hoạt động (Audit Log)**.
:::

## 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](/vi/mina-mcp/mina-assistant/) (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)

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