# Kết nối MCP

> Kết nối Claude Code, Claude Desktop hoặc Cursor với kho bài qua MCP, đăng nhập OAuth, danh sách tool và cách xử lý client không hỗ trợ CIMD.

InSecLab Papers là một máy chủ Model Context Protocol (MCP): bạn hỏi Claude hay Cursor "bài ISL-2026-0012 đang ở trạng thái nào" mà không cần mở web. Quyền vẫn như trên web: bạn chỉ thấy công trình mình được xem.

## Thông tin kết nối

| Mục | Giá trị |
| --- | --- |
| Endpoint | `https://papers-inseclab.khoi.pro/mcp` (JSON-RPC qua HTTP) |
| Đăng nhập | OAuth của chính ứng dụng; không dùng token CLI `papers_…` |
| Đăng ký client | Client ID Metadata Document (CIMD); đăng ký động (DCR) tắt |

## Client hỗ trợ CIMD

Lần kết nối đầu, client mở trình duyệt tới trang đăng nhập rồi trang **consent** (hiện tên client, lab, quyền). Bấm **Cho phép**; client nhận token sống 5 phút và tự làm mới.

**Claude Code**

```sh
claude mcp add --transport http papers https://papers-inseclab.khoi.pro/mcp
# trong phiên Claude Code: /mcp → chọn papers → Authenticate
```

**Claude Desktop**: Settings → Connectors → *Add custom connector* → URL `https://papers-inseclab.khoi.pro/mcp` → Connect.

**Cursor**: thêm vào `~/.cursor/mcp.json` rồi bật `papers` trong Settings → MCP:

```json
{ "mcpServers": { "papers": { "url": "https://papers-inseclab.khoi.pro/mcp" } } }
```

## Tool

| Tool | Việc | Ghi dữ liệu |
| --- | --- | --- |
| `works_search` | Tìm công trình với bộ lọc như bảng trên web | Không |
| `work_get` | Một công trình: mã, tiêu đề, thành viên, lần nộp, phiên bản mới nhất | Không |
| `version_list` | Các phiên bản của công trình, mới nhất trước | Không |
| `check_report_get` | Kết quả mới nhất của 10 kiểm tra | Không |
| `diff_get` | Đường dẫn 600 giây tới PDF latexdiff | Không |
| `latex_flatten` | Đường dẫn 600 giây tới tệp `.tex` đã gộp | Không |
| `version_upload` | Tạo phiên bản mới (không ghi đè) | Có: client sẽ hỏi bạn xác nhận |

Lỗi trả về dạng `{ "ok": false, "error": { "code": "not_found", … } }`. Công trình bạn không có quyền xem được báo giống hệt công trình không tồn tại.

## Client không hỗ trợ CIMD

Client báo `invalid_client` hoặc "client registration failed" nghĩa là nó không hỗ trợ CIMD. Nhờ **quản trị** tạo một client công khai (PKCE, không secret) và gửi bạn `client_id`; cấu hình `client_id` đó trong ứng dụng rồi kết nối như trên.

Client chỉ biết **device flow** thì xin mã ở `POST /api/auth/device/code` với `client_id` đó, mở `https://papers-inseclab.khoi.pro/device`, nhập mã và bấm **Cho phép**. Mã sống 15 phút, mỗi mã duyệt một lần; phiên phải đã qua 2FA. Trang `/device` dùng chung với `papers login` nhưng hai loại mã khác nhau.