# Kết nối AI agent qua MCP

> Kết nối Claude Code, Cursor, VS Code, Codex, ChatGPT, Claude.ai, Lovable, Windsurf hoặc client stdio với máy chủ MCP của Belvador bằng OAuth hoặc token chỉ đọc.

Máy chủ MCP của Belvador cho AI agent bạn đang dùng — trong trình soạn code, terminal hay ứng dụng chat — đọc issue, event, trace, log và monitor của workspace này, và tìm trong tài liệu này. Máy chủ dùng [Model Context Protocol](https://modelcontextprotocol.io) (phiên bản 2026-07-28, 2025-11-25).

## Từ xa hay cục bộ

| | Từ xa | Cục bộ |
|---|---|---|
| Địa chỉ | `https://api.belvador.dev/mcp` | `npx -y @belvador/mcp@0.6.0` (Node.js 20.10 trở lên) |
| Đăng nhập | OAuth hoặc token | Token từ `BELVADOR_TOKEN` hoặc keychain của máy |
| Dữ liệu trên node | Đọc qua edge cho từng lần gọi; api.belvador.dev không lưu và không ghi log | Đọc thẳng từ edge.belvador.dev bằng vé ngắn hạn; không bao giờ đi qua api.belvador.dev |

Hai cách có cùng công cụ, cùng mô tả và cùng câu trả lời.

## Cách nhanh nhất: Cài đặt → AI agent

Trong Belvador, mở **Cài đặt → AI agent** của workspace:

1. Chọn công cụ của bạn.
2. Chọn cách đăng nhập. Nên dùng OAuth nếu công cụ hỗ trợ: bạn bấm cho phép trên belvador.dev và không phải sao chép token đi đâu.
3. Chọn bộ công cụ rồi sao chép cấu hình hiện cho công cụ đó.
4. Nếu dùng token, bấm **Tạo token chỉ đọc** (trang sẽ hỏi mã xác thực), đặt token vào `BELVADOR_TOKEN` rồi bấm **Kiểm kết nối**. Trang hỏi máy chủ MCP danh sách công cụ và cho biết token thấy bao nhiêu công cụ. Với OAuth, kết nối hiện ngay trên trang sau khi bạn cho phép.

## Công cụ được hỗ trợ

| Công cụ | OAuth | API token | Cục bộ (stdio) | Nguồn |
|---|---|---|---|---|
| Claude Code | Có | Có | Có | [code.claude.com](https://code.claude.com/docs/en/mcp) |
| Cursor | Có | Có | Có | [cursor.com](https://cursor.com/docs/mcp) |
| VS Code | Có | Có | Có | [code.visualstudio.com](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) |
| Codex | Có | Có | Có | [developers.openai.com](https://developers.openai.com/codex/mcp) |
| ChatGPT | Có | — | — | [developers.openai.com](https://developers.openai.com/api/docs/guides/custom-mcp-server) |
| Claude.ai | Có | — | — | [claude.com](https://claude.com/docs/connectors/custom/remote-mcp) |
| Lovable | Có | Có | — | [docs.lovable.dev](https://docs.lovable.dev/integrations/custom-mcp) |
| Windsurf | Có | Có | Có | [docs.devin.ai](https://docs.devin.ai/windsurf/plugins/cascade/mcp) |
| stdio / khác | — | — | Có | [modelcontextprotocol.io](https://modelcontextprotocol.io/docs/concepts/transports) |

Định dạng cấu hình đã được đối chiếu với tài liệu của từng hãng ngày 2026-10-26. Nếu menu đã đổi chỗ, hãy dùng mục "thêm máy chủ MCP từ xa" của công cụ với `https://api.belvador.dev/mcp`.

## Cài theo từng công cụ

### Claude Code

Bằng OAuth:

```bash
claude mcp add --transport http --scope user belvador https://api.belvador.dev/mcp
```

Mở Claude Code, gõ `/mcp`, chọn `belvador` rồi chọn Authenticate.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

```bash
claude mcp add --transport http --scope project belvador https://api.belvador.dev/mcp \
  --header 'Authorization: Bearer ${BELVADOR_TOKEN}'
```

Giữ nguyên dấu nháy đơn: Claude Code lưu `${BELVADOR_TOKEN}` vào `.mcp.json` và đọc biến khi khởi động, nên token không bị ghi vào file.

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

Cục bộ:

```bash
claude mcp add --scope project --transport stdio \
  --env 'BELVADOR_TOKEN=${BELVADOR_TOKEN}' \
  belvador -- npx -y @belvador/mcp@0.6.0
```

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

### Cursor

Bằng OAuth:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "belvador": {
      "url": "https://api.belvador.dev/mcp"
    }
  }
}
```

Dùng `~/.cursor/mcp.json` cho mọi project hoặc `.cursor/mcp.json` trong một project.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "belvador": {
      "url": "https://api.belvador.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Dùng `~/.cursor/mcp.json` cho mọi project hoặc `.cursor/mcp.json` trong một project.

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

Cục bộ:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "belvador": {
      "command": "npx",
      "args": [
        "-y",
        "@belvador/mcp@0.6.0"
      ],
      "env": {
        "BELVADOR_TOKEN": "${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Dùng `~/.cursor/mcp.json` cho mọi project hoặc `.cursor/mcp.json` trong một project.

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

### VS Code (GitHub Copilot)

Bằng OAuth:

```json title=".vscode/mcp.json"
{
  "servers": {
    "belvador": {
      "type": "http",
      "url": "https://api.belvador.dev/mcp"
    }
  }
}
```

Bấm Start phía trên `belvador` trong file và cho phép trong trình duyệt khi VS Code hỏi.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

```json title=".vscode/mcp.json"
{
  "servers": {
    "belvador": {
      "type": "http",
      "url": "https://api.belvador.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

Cục bộ:

```json title=".vscode/mcp.json"
{
  "servers": {
    "belvador": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@belvador/mcp@0.6.0"
      ],
      "env": {
        "BELVADOR_TOKEN": "${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

### Codex

Bằng OAuth:

```bash
codex mcp add belvador --url https://api.belvador.dev/mcp
codex mcp login belvador
```

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

```toml title="~/.codex/config.toml"
[mcp_servers.belvador]
url = "https://api.belvador.dev/mcp"
bearer_token_env_var = "BELVADOR_TOKEN"
```

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

Cục bộ:

```toml title="~/.codex/config.toml"
[mcp_servers.belvador]
command = "npx"
args = ["-y", "@belvador/mcp@0.6.0"]
env_vars = ["BELVADOR_TOKEN"]
```

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

### ChatGPT

Trong ChatGPT mở Plugins → + → Add custom MCP server (tài khoản hoặc workspace cần được bật developer mode).

```text
https://api.belvador.dev/mcp
```

Dán URL trên vào Server URL, chọn xác thực OAuth, chấp nhận cảnh báo rồi tạo.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

### Claude.ai

Trong Claude mở Customize → Connectors → Add custom connector (chủ tổ chức: Organization settings → Connectors → Add → Custom → Web).

```text
https://api.belvador.dev/mcp
```

Dán URL trên, thêm rồi bấm Connect. Để trống ô OAuth client — Belvador tự đăng ký client.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

### Lovable

Bằng OAuth:

Trong Lovable mở Connectors → Add custom → MCP server, đặt tên Belvador và giữ Direct connection.

```text
https://api.belvador.dev/mcp
```

Dán URL trên, giữ OAuth rồi bấm Add & authorize.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

Trong Lovable mở Connectors → Add custom → MCP server, đặt tên Belvador và giữ Direct connection.

```text
https://api.belvador.dev/mcp
```

Dán URL trên, chọn Bearer token or API key, dán token vào đúng ô đó rồi bấm Add server.

### Windsurf

Bằng OAuth:

```json title="mcp_config.json"
{
  "mcpServers": {
    "belvador": {
      "serverUrl": "https://api.belvador.dev/mcp"
    }
  }
}
```

Mở bằng Cascade → MCP → Open MCP config file rồi làm mới danh sách server.

Client sẽ mở belvador.dev trong trình duyệt: chọn workspace và quyền cho agent rồi bấm cho phép. Sau đó kết nối hiện ở Tài khoản → Ứng dụng đã kết nối.

Bằng token:

```json title="mcp_config.json"
{
  "mcpServers": {
    "belvador": {
      "serverUrl": "https://api.belvador.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Mở bằng Cascade → MCP → Open MCP config file rồi làm mới danh sách server.

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

Cục bộ:

```json title="mcp_config.json"
{
  "mcpServers": {
    "belvador": {
      "command": "npx",
      "args": [
        "-y",
        "@belvador/mcp@0.6.0"
      ],
      "env": {
        "BELVADOR_TOKEN": "${env:BELVADOR_TOKEN}"
      }
    }
  }
}
```

Mở bằng Cascade → MCP → Open MCP config file rồi làm mới danh sách server.

Đặt token vào biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent (shell profile hoặc trình quản lý bí mật). File cấu hình chỉ ghi tên biến — đừng dán token vào file hay vào khung chat.

### Client stdio khác

```bash
npx -y @belvador/mcp@0.6.0
```

```json
{
  "mcpServers": {
    "belvador": {
      "command": "npx",
      "args": [
        "-y",
        "@belvador/mcp@0.6.0"
      ],
      "env": {
        "BELVADOR_TOKEN": "<from your secret store>"
      }
    }
  }
}
```

Mọi MCP client chạy được lệnh cục bộ đều dùng được. Khi không có `BELVADOR_TOKEN`, gói đọc keychain của máy: service `belvador.dev`, account `mcp`.

```bash
# macOS
security add-generic-password -s belvador.dev -a mcp -w
# Linux (libsecret)
secret-tool store --label=Belvador service belvador.dev account mcp
```

## Bộ công cụ và công cụ

Ba bộ bật sẵn: `investigate` (issue, event, trace, log), `reliability` (monitor) và `docs`. Muốn ít hơn thì thêm `?toolsets=investigate,docs` vào URL, hoặc `--toolsets=investigate,docs` cho gói cục bộ. Token còn giới hạn thêm: công cụ chỉ hiện khi token có quyền mà công cụ cần, nên agent không bao giờ thấy công cụ sẽ từ chối nó.

| Công cụ | Bộ | Quyền cần | Chỉ đọc |
|---|---|---|---|
| `get_workspace` | investigate | `org:read` | Có |
| `list_projects` | investigate | `projects:read` | Có |
| `search_issues` | investigate | `issues:read` | Có |
| `get_issue` | investigate | `issues:read` | Có |
| `list_events` | investigate | `events:read` | Có |
| `get_event` | investigate | `events:read` | Có |
| `get_trace` | investigate | `traces:read` | Có |
| `search_spans` | investigate | `traces:read` | Có |
| `query_logs` | investigate | `logs:read` | Có |
| `query_metrics` | investigate | `metrics:read` | Có |
| `correlate` | investigate | `traces:read` | Có |
| `release_health` | investigate | `releases:read` | Có |
| `list_monitors` | reliability | `monitors:read` | Có |
| `get_monitor_status` | reliability | `monitors:read` | Có |
| `list_alerts` | reliability | `alerts:read` | Có |
| `list_incidents` | reliability | `incidents:read` | Có |
| `get_incident` | reliability | `incidents:read` | Có |
| `get_coverage` | reliability | `coverage:read` | Có |
| `verify_integration` | reliability | `projects:write` | Không — gửi một event thử |
| `search_operations` | configure | Quyền của thao tác | Có |
| `describe_operation` | configure | Quyền của thao tác | Có |
| `plan_change` | configure | Quyền của thao tác | Có |
| `apply_change` | configure | Quyền của thao tác | Không — đổi cấu hình; thao tác nhạy cảm chờ người duyệt |
| `get_operation` | configure | Quyền của thao tác | Có |
| `search_docs` | docs | — | Có |
| `get_doc` | docs | — | Có |

## Đổi cấu hình: `configure`

Bộ `configure` tắt sẵn. Bật bằng `?toolsets=investigate,reliability,docs,configure` trên URL, hoặc `--toolsets=…` cho gói cục bộ. Bộ này chỉ hiện khi token hoặc kết nối OAuth có ít nhất một quyền ghi, và phủ mọi thao tác đổi cấu hình của [REST API](https://belvador.dev/vi/docs/reference/api):

1. `search_operations` tìm thao tác ("xoay khoá DSN", "thêm monitor"); `describe_operation` cho biết các trường, quyền cần có và có phải chờ người duyệt không.
2. `plan_change` kiểm tra các trường mà không thay đổi gì: lỗi, quyền còn thiếu, có cần duyệt không và, với thao tác sửa, giá trị hiện tại, những gì sẽ đổi và `etag`.
3. `apply_change` thực hiện thay đổi với `idempotency_key` — cùng khoá không bao giờ áp dụng hai lần — và, với thao tác sửa, `if_match` bằng etag đó.
4. Thay đổi nhạy cảm (khoá, thành viên, token, nơi nhận cảnh báo, thay đổi node) trả `approval_required` kèm link tới belvador.dev. Client dùng MCP 2026-07-28 có hỗ trợ sẽ tự mở link; nếu không, agent hiện link cho bạn. Một người duyệt bằng mã xác thực trong vòng 15 phút, rồi `get_operation` — hoặc gọi lại `apply_change` với cùng khoá — cho biết kết quả. Khoá và token mới chỉ hiện trên trang đó, không bao giờ cho agent. Xem [Duyệt thao tác](https://belvador.dev/vi/docs/reference/api#duyet-thao-tac).

Những gì người duyệt phải tự gõ — tên xác nhận khi xoá, token bot, webhook URL hay mật khẩu mail — không nằm trong đầu vào của công cụ nào; trang duyệt sẽ hỏi.

## Token

- **Token chỉ đọc từ Cài đặt → AI agent.** Mọi quyền đọc trừ nhật ký kiểm toán, chỉ workspace này, dùng được 90 ngày trừ khi workspace đặt giới hạn ngắn hơn. Cần quyền, project hay hạn dùng khác thì tạo ở **Tài khoản → Token API** — xem [DSN, khoá ingest, ping URL, token và vé node](https://belvador.dev/vi/docs/security/credentials).
- **Để ở đâu.** Trong biến môi trường `BELVADOR_TOKEN` của chương trình chạy agent, hoặc keychain của máy với gói cục bộ. Không bao giờ để trong file cấu hình, trong repository hay trong khung chat.
- **OAuth.** Access token sống 60 phút và được công cụ tự gia hạn; kết nối hết hiệu lực sau 30 ngày không dùng.
- **Thu hồi** token ở **Tài khoản → Token API**, kết nối OAuth ở **Tài khoản → Ứng dụng đã kết nối**; trong vòng một phút là hết dùng được.

## Agent nhận được gì

- Chữ từ ứng dụng của bạn — thông báo lỗi, stack trace, dòng log, breadcrumb — nằm trong trường `untrusted` kèm nguồn gốc. Máy chủ dặn mô hình không làm theo chỉ dẫn nằm trong đó và không mở link lấy từ đó. Ký tự vô hình được hiện thành dấu nhìn thấy được.
- Mỗi câu trả lời của công cụ tối đa 64 KB; danh sách dài được chia trang.
- Truy vấn trace và log cần khoảng thời gian tối đa 168 giờ.
- Lượt gọi tính chung giới hạn với [REST API](https://belvador.dev/vi/docs/reference/api): 300 lượt mỗi phút cho mỗi token.
- Khi node mất kết nối, công cụ đọc dữ liệu trả `NODE_OFFLINE`; công cụ của control plane và tài liệu vẫn chạy.

## Quyền riêng tư

Những gì agent đọc sẽ được gửi tới nhà cung cấp mô hình AI bạn chọn. Belvador không thấy và không kiểm soát được nhà cung cấp đó giữ gì. Chỉ kết nối những project và môi trường agent cần — token giới hạn được theo project và môi trường ở **Tài khoản → Token API**.

## Khắc phục sự cố

| Bạn thấy | Cách xử lý |
|---|---|
| 401, hoặc "token sai, đã hết hạn hoặc đã bị thu hồi" | Tạo token mới, hoặc kết nối lại bằng OAuth |
| 403 `insufficient_scope` | Công cụ cần quyền ghi trong câu trả lời; tạo token có quyền đó hoặc cho phép lại kết nối OAuth |
| `approval_required` | Mở link, xem thay đổi và duyệt bằng mã xác thực trong vòng 15 phút; rồi bảo agent kiểm tra lại |
| Danh sách công cụ trống | Token không có quyền đọc dữ liệu nào của workspace này |
| Cục bộ: `no token` | Đặt `BELVADOR_TOKEN` cho chương trình chạy agent, hoặc thêm mục keychain |
| Cục bộ: `the API did not answer` sau proxy công ty | Đưa chứng chỉ của proxy cho Node.js bằng `NODE_EXTRA_CA_CERTS` |