Máy chủ MCP AI Drive
Tìm và đọc tài liệu Keural Drive từ các client MCP bên ngoài như Claude Desktop.
Keural cũng cung cấp Drive dưới dạng máy chủ MCP. Khi một client MCP bên ngoài kết nối tới máy chủ này, client có thể tìm kiếm và đọc từng trang tài liệu Keural Drive mà người dùng được cấp khóa có quyền xem. Plugin kết nối hệ thống bên ngoài với Keural, còn máy chủ này kết nối tài liệu Keural với AI bên ngoài.
Máy chủ này xác thực bằng khóa API của tổ chức. Khóa do Keural cấp, vì vậy hãy yêu cầu người phụ trách triển khai của bạn cấp khóa. Khóa hoạt động với quyền của đúng một người dùng được cấp khóa, và phải có quyền drive:read. Nếu thu hồi khóa, các kết nối hiện có sẽ bị chặn trong vòng 1 phút.
Thông tin kết nối
| Mục | Giá trị |
|---|---|
| Phương thức truyền tải | MCP Streamable HTTP |
| Địa chỉ | https://<tên miền máy chủ agent của môi trường>/core/v1/mcp-drive |
| Xác thực | Authorization: Bearer <khóa API của tổ chức> (trong mọi yêu cầu) |
Phương thức yêu cầu
| Phương thức | Công dụng |
|---|---|
POST | Một yêu cầu JSON-RPC. Phản hồi luôn là một application/json. Thông báo (notifications/*) trả về 202 không có nội dung. |
GET | Luồng sự kiện từ máy chủ. Cần Accept: text/event-stream và Mcp-Session-Id. Gửi keepalive mỗi 15 giây và tiếp tục nhận bằng Last-Event-ID. |
DELETE | Kết thúc phiên. Cần Mcp-Session-Id và trả về 204. |
- Khi
initializethành công, ID phiên được trả về trong header phản hồiMcp-Session-Id. Phiên là tùy chọn; bạn cũng có thể chỉ gửiPOSTmà không cần phiên. Phiên được giữ trong 1 giờ sau yêu cầu cuối cùng và gắn với khóa đã tạo ra nó. - Header
MCP-Protocol-Versionlà tùy chọn. Nếu gửi, giá trị phải là2025-06-18. - Tên máy chủ là
keural-ai-drive, và chỉ cung cấptools.
Lỗi HTTP
Lỗi ở tầng HTTP không theo định dạng JSON-RPC, vì vậy hãy kiểm tra mã trạng thái trước.
| Trạng thái | Nguyên nhân |
|---|---|
401 | Thiếu khóa hoặc khóa sai; khóa đã thu hồi hoặc hết hạn |
403 | Khóa không có quyền drive:read |
400 | MCP-Protocol-Version không được hỗ trợ, phân tích JSON thất bại (-32700), hoặc GET·DELETE thiếu ID phiên |
404 | ID phiên không tồn tại hoặc đã hết hạn |
405 | GET thiếu Accept: text/event-stream |
Lỗi ở tầng JSON-RPC được trả về với 200 và đối tượng error. Phương thức hoặc công cụ không tồn tại trả về -32601, yêu cầu sai định dạng trả về -32600.
Công cụ
| Công cụ | Đầu vào | Mô tả |
|---|---|---|
list_files | Không có | Danh sách tài liệu bạn có thể xem (tên, id, ngày tải lên, ngày sửa đổi và người tải lên nếu là người khác). Tài liệu Drive và tệp đính kèm trong chat hiển thị chung và được phân biệt bằng origin. Tối đa 500; nếu nhiều hơn sẽ thêm truncated: true |
search_drive | query | Tìm kiếm theo ngữ nghĩa trong nội dung tài liệu, trả về các đoạn liên quan và thông tin trích dẫn |
read_document_page | file_id, page | Đọc toàn văn một trang của tài liệu. Lấy file_id từ kết quả của hai công cụ trên; page đánh số từ 1 |
Kết quả của mỗi công cụ được trả về dưới dạng chuỗi JSON trong content[0].text.
| Công cụ | JSON trong text |
|---|---|
list_files | {"files":[{"name","id","created_date","modified_date","owner_name","origin"}], "truncated": false}. Ngày theo định dạng yyyy-MM-dd HH:mm |
search_drive | {"sources":[{"id","name","url","contents":[…]}]} |
read_document_page | {"file_id","page","rows":[…]} |
Nếu công cụ chạy thất bại, kết quả trả về isError: true và {"error": "…"} (không phải lỗi JSON-RPC). Tài liệu bạn không có quyền xem hoặc không tồn tại đều nhận cùng phản hồi: file not found or not accessible.
Ví dụ cấu hình client
Đăng ký địa chỉ và header vào client hỗ trợ máy chủ MCP từ xa. Ví dụ dưới đây chỉ minh họa định dạng. Định dạng cấu hình khác nhau tùy client, vì vậy hãy làm theo hướng dẫn thêm máy chủ MCP từ xa của client bạn đang dùng.
{
"mcpServers": {
"keural-drive": {
"type": "http",
"url": "https://<tên miền máy chủ agent của môi trường>/core/v1/mcp-drive",
"headers": { "Authorization": "Bearer <khóa API của tổ chức>" }
}
}
}Phiên bản giao thức MCP được hỗ trợ là 2025-06-18.