Kết nối AI agent qua MCP

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 (phiên bản 2026-07-28, 2025-11-25).

Từ xa hay cục bộ#

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ợ#

Đị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:

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:

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ộ:

claude mcp add --scope project --transport stdio \  --env 'BELVADOR_TOKEN=${BELVADOR_TOKEN}' \  belvador -- npx -y @belvador/mcp@0.4.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:

{  "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:

{  "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ộ:

{  "mcpServers": {    "belvador": {      "command": "npx",      "args": [        "-y",        "@belvador/mcp@0.4.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:

{  "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:

{  "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ộ:

{  "servers": {    "belvador": {      "type": "stdio",      "command": "npx",      "args": [        "-y",        "@belvador/mcp@0.4.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:

codex mcp add belvador --url https://api.belvador.dev/mcpcodex 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:

[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ộ:

[mcp_servers.belvador]command = "npx"args = ["-y", "@belvador/mcp@0.4.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).

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

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.

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.

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:

{  "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:

{  "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ộ:

{  "mcpServers": {    "belvador": {      "command": "npx",      "args": [        "-y",        "@belvador/mcp@0.4.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#

npx -y @belvador/mcp@0.4.0

{  "mcpServers": {    "belvador": {      "command": "npx",      "args": [        "-y",        "@belvador/mcp@0.4.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.

# macOSsecurity 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ó.

Đổ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:

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.

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.

• Để ở đâ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: 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ố#