#NocoBase MCP

Sau khi kích hoạt Plugin dịch vụ NocoBase MCP, ứng dụng NocoBase sẽ cung cấp một interface dịch vụ MCP ra ngoài, để các MCP client truy cập và gọi các API của NocoBase.

#Địa chỉ dịch vụ

• Ứng dụng chính:

  http(s)://<host>:<port>/api/mcp

• Ứng dụng con:

  http(s)://<host>:<port>/api/__app/<app_name>/mcp

Địa chỉ này sử dụng giao thức truyền tải streamable HTTP.

#Năng lực cung cấp

#Công cụ chung

Có thể dùng để thao tác với bảng dữ liệu

#Các interface kernel NocoBase và các Plugin

Hỗ trợ điều khiển những package nào được MCP expose qua header x-mcp-packages, ví dụ:

x-mcp-packages: @nocobase/server,plugin-workflow*,plugin-users

Header này hỗ trợ truyền tên package đầy đủ, khi không có scope sẽ tự động bổ sung thành @nocobase/.

Mặc định không tải interface của các package khác ngoài công cụ chung, khuyến nghị sử dụng cách NocoBase CLI để thao tác với các tính năng hệ thống khác.

Các package thường dùng:

Bạn có thể tham khảo thêm các package và interface liên quan qua Plugin API documentation.

#Phương thức xác thực

#Xác thực qua API Key

Sử dụng API key được tạo qua Plugin API keys để gọi interface dịch vụ MCP, quyền hạn được quyết định bởi vai trò gắn với API key đó.

#Xác thực qua OAuth

Sử dụng access token có được sau khi xác thực OAuth để gọi interface dịch vụ MCP, quyền hạn được quyết định bởi người dùng đã xác thực. Nếu người dùng có nhiều vai trò, có thể đặt vai trò gọi qua header x-role.

#Bắt đầu nhanh

#Codex

#Sử dụng xác thực API Key

Trước tiên kích hoạt Plugin API Keys và tạo một API Key.

export NOCOBASE_API_TOKEN=<your_api_key>
codex mcp add nocobase --url https://<host>:<port>/api/mcp --bearer-token-env-var NOCOBASE_API_TOKEN

#Sử dụng xác thực OAuth

Trước tiên kích hoạt Plugin IdP: OAuth.

codex mcp add nocobase --url https://<host>:<port>/api/mcp
codex mcp login nocobase --scopes mcp,offline_access

#Claude Code

#Sử dụng xác thực API Key

Trước tiên kích hoạt Plugin API Keys và tạo một API Key.

claude mcp add --transport http nocobase https://<host>:<port>/api/mcp --header "Authorization: Bearer <your_api_key>"

#Sử dụng xác thực OAuth

Trước tiên kích hoạt Plugin IdP: OAuth.

claude mcp add --transport http nocobase https://<host>:<port>/api/mcp

Sau khi thực thi xong, mở Claude và chọn dịch vụ MCP tương ứng để đăng nhập:

claude
/mcp

#OpenCode

#Sử dụng xác thực API Key

Trước tiên kích hoạt Plugin API Keys và tạo một API Key. Cấu hình opencode.json:

{
  "mcp": {
    "nocobase": {
      "type": "remote",
      "url": "https://<host>:<port>/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <your_api_key>"
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

#Sử dụng xác thực OAuth

Trước tiên kích hoạt Plugin IdP: OAuth. Cấu hình opencode.json:

{
  "mcp": {
    "nocobase": {
      "type": "remote",
      "url": "https://<host>:<port>/api/mcp",
      "enabled": true
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

Đăng nhập xác thực

opencode mcp auth nocobase

Debug

opencode mcp debug nocobase