# MCP

> Kết nối Claude Code, Codex, Cursor hoặc VS Code với MCP server của Browlix và dùng mọi thao tác API như một tool.

MCP server của Browlix đưa danh mục API v1 thành các tool, cùng quyền, giới hạn, chống trùng lệnh và kiểm toán như HTTP.

- Endpoint: `https://browlix.com/api/public/mcp`
- Giao thức truyền: Streamable HTTP, không trạng thái — mỗi `POST` mang khoá API, nên kết nối lại chỉ là yêu cầu kế tiếp.
- Phiên bản giao thức (mới nhất trước):

- `2026-07-28` — thế hệ mới (thông tin theo từng yêu cầu, `server/discover`, không bắt tay)
- `2025-11-25`, `2025-06-18`, `2025-03-26` — thế hệ cũ (bắt tay `initialize`)

Client dùng `2026-07-28` gửi phiên bản và khả năng của nó trong mọi yêu cầu (các header `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` lặp lại nội dung body) và có thể gọi `server/discover` trước; không có bước bắt tay. Client dùng phiên bản cũ hơn bắt đầu bằng `initialize` và nhận lại đúng phiên bản của mình nếu có trong danh sách, nếu không thì bản cũ mới nhất. Phiên bản không biết bị từ chối với lỗi `-32022` kèm danh sách hỗ trợ.

## Kết nối client

Để khoá trong biến môi trường hoặc ô nhập bí mật của client — không bao giờ trong file cấu hình.

```bash tab="Claude Code"
export BROWLIX_API_KEY="bxk_…"
claude mcp add --transport http --scope user browlix https://browlix.com/api/public/mcp \
  --header 'Authorization: Bearer ${BROWLIX_API_KEY}'
```

```bash tab="Codex CLI"
export BROWLIX_API_KEY="bxk_…"
codex mcp add browlix --url https://browlix.com/api/public/mcp --bearer-token-env-var BROWLIX_API_KEY
```

```json tab=Cursor
{
  "mcpServers": {
    "browlix": {
      "url": "https://browlix.com/api/public/mcp",
      "headers": { "Authorization": "Bearer ${env:BROWLIX_API_KEY}" }
    }
  }
}
```

```json tab="VS Code"
{
  "inputs": [{ "type": "promptString", "id": "browlix-api-key", "description": "Browlix API key", "password": true }],
  "servers": {
    "browlix": {
      "type": "http",
      "url": "https://browlix.com/api/public/mcp",
      "headers": { "Authorization": "Bearer ${input:browlix-api-key}" }
    }
  }
}
```

Cursor đọc `~/.cursor/mcp.json`; VS Code đọc `.vscode/mcp.json` trong thư mục dự án. Trên web, **Cài đặt → Khoá API** có sẵn các đoạn cấu hình này.

## Tool

- Mỗi thao tác một tool, tên là id với dấu gạch dưới: `sessions.start` → `sessions_start`. Đầu vào là các trường path, query và body đặt cạnh nhau.
- `tools/list` chỉ trả về tool mà khoá đang được phép dùng.
- Tool đọc được đánh dấu chỉ đọc; tool xoá hoặc kết thúc thứ gì đó được đánh dấu phá huỷ.
- `docs_search` và `docs_fetch` đọc tài liệu này, dùng được với mọi khoá hợp lệ.
- Mọi tool công bố `outputSchema` (từ phiên bản `2025-06-18`); gọi thành công trả về đúng JSON như HTTP trong `structuredContent` và dạng văn bản. Trường mới có thể được thêm bất cứ lúc nào — hãy bỏ qua trường bạn không biết.
- Với `2026-07-28`, `tools/list` được lưu đệm 5 phút theo từng khoá (`cacheScope: private`).

## Thao tác ghi và mất phản hồi

Tool ghi nhận `command_id`. Nếu agent không truyền, server tự tạo và trả lại trong kết quả. Sau khi mất kết nối, gọi `receipts_get` với id đó thay vì gọi lại tool ghi.

## Lỗi và phản hồi

Lỗi trả về dưới dạng kết quả tool có `isError: true` và cùng `error.code` như HTTP. Với lỗi Browlix có thể cải thiện (`UNKNOWN`, `VALIDATION_FAILED`, `CONFLICT`, `UNSUPPORTED`…), kết quả kèm gợi ý về `feedback_submit` — xem [Phản hồi từ agent](https://browlix.com/docs/feedback).

## Client đã kiểm

Mỗi dòng đã được chạy với MCP server của Browlix; client nào chưa chạy được thì ghi rõ.

| Client | Phiên bản | Giao thức | Kết quả | Ngày kiểm | Ghi chú |
|---|---|---|---|---|---|
| Claude Code | 2.1.311 | `2026-07-28` | chạy được | 2026-10-27 | server/discover rồi tools/list (`claude mcp list` → Connected) |
| @modelcontextprotocol/client (TypeScript SDK v2) | 2.4.0 | `2026-07-28` | chạy được | 2026-10-27 | chốt cứng và tự thương lượng; liệt kê, gọi, lỗi có kiểu, client tự kiểm outputSchema |
| @modelcontextprotocol/sdk (TypeScript) | 1.32.2 | `2025-11-25` | chạy được | 2026-10-27 | bắt tay initialize; client tự kiểm outputSchema |
| @modelcontextprotocol/sdk (TypeScript) | 1.17.5 | `2025-06-18` | chạy được | 2026-10-27 | bắt tay initialize; client tự kiểm outputSchema |
| @modelcontextprotocol/sdk (TypeScript) | 1.11.5 | `2025-03-26` | chạy được | 2026-10-27 | không gửi header MCP-Protocol-Version; danh sách công cụ không kèm outputSchema |
| Codex CLI | 0.164.0 | — | chỉ cấu hình | 2026-10-27 | `codex mcp add … --bearer-token-env-var` được chấp nhận; phiên thật cần đăng nhập OpenAI, chưa chạy trong lab |
| Cursor | — | — | chưa chạy | 2026-10-27 | ứng dụng desktop, chưa chạy trong lab; cấu hình theo tài liệu Cursor |
| VS Code | — | — | chưa chạy | 2026-10-27 | ứng dụng desktop, chưa chạy trong lab; cấu hình theo tài liệu VS Code |