Cài đặt và sử dụng — MCP Server

Tổng quan

Plugin MCP Server biến Digiforce thành một Model Context Protocol (MCP) server chuẩn — cho phép AI assistants (Claude, Cursor, GPT, v.v.) truy cập dữ liệu và thực thi thao tác CRUD trên Digiforce thông qua giao thức MCP.

Plugin tự động tạo MCP tools từ:

Swagger/OpenAPI definitions của các plugin đã cài
CRUD tools tổng quát cho tất cả Collection (list, get, create, update, destroy, query)

Bước 1: Kích hoạt Plugin

Truy cập Settings → Plugin Manager, tìm plugin-mcp-server và bật plugin. Khởi động lại server.

Bước 2: Cấu hình xác thực

Plugin hỗ trợ hai phương thức xác thực:

OAuth2 (khuyến nghị)

Nếu plugin idp-oauth đã được cài đặt, MCP Server tự động đăng ký làm OAuth2 Resource Server:

Issuer: Lấy từ IdP OAuth provider
Scopes: mcp, offline_access
Token format: JWT (RS256)
Resource metadata: Tự động expose tại /.well-known/oauth-protected-resource

AI client kết nối qua OAuth2 flow chuẩn, nhận Bearer token để gọi MCP endpoint.

Bearer Token

Nếu không dùng OAuth2, AI client có thể sử dụng Bearer token của người dùng Digiforce đã đăng nhập. Token này kế thừa toàn bộ quyền của người dùng.

Bước 3: Kết nối từ AI Agent

Cấu hình AI agent để kết nối đến MCP Server:

json

{
  "mcpServers": {
    "digiforce": {
      "url": "https://your-domain/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Tham số	Mô tả
`url`	Endpoint MCP: `{API_BASE_PATH}/mcp` (mặc định: `/api/mcp`)
`transport`	`streamable-http` (Streamable HTTP Transport)
`headers`	Bearer token hoặc OAuth2 access token

Lọc tools theo package

Gửi header x-mcp-packages để chỉ expose tools từ các package cụ thể:

x-mcp-packages: plugin-data-source-main, plugin-workflow*

Mặc định, plugin expose tools từ các package sau:

Package	Mô tả
`@digiforce-nc/plugin-data-source-main`	Data source chính
`@digiforce-nc/plugin-data-source-manager`	Quản lý data source
`@digiforce-nc/plugin-workflow*`	Tất cả plugin workflow
`@digiforce-nc/plugin-acl`	Quản lý quyền
`@digiforce-nc/plugin-users`	Quản lý người dùng
`@digiforce-nc/plugin-auth`	Xác thực
`@digiforce-nc/plugin-client`	Client framework
`@digiforce-nc/plugin-ui-core`	UI core
`@digiforce-nc/plugin-ai`	AI features

CRUD Tools tổng quát

Plugin tự động tạo 6 CRUD tools cho tất cả Collection:

Tool	Mô tả	Ví dụ sử dụng
`resource_list`	Liệt kê records (hỗ trợ filter, sort, pagination)	Lấy danh sách users
`resource_get`	Lấy một record theo primary key	Lấy chi tiết user ID=5
`resource_create`	Tạo record mới	Tạo order mới
`resource_update`	Cập nhật record	Cập nhật trạng thái order
`resource_destroy`	Xoá record	Xoá record theo ID
`resource_query`	Aggregate query (measures, dimensions, group by)	Thống kê doanh thu theo tháng

Ví dụ gọi `resource_list`

json

{
  "name": "resource_list",
  "arguments": {
    "resource": "users",
    "filter": { "email.$includes": "company.com" },
    "fields": ["id", "email", "displayname"],
    "sort": ["-createdAt"],
    "page": 1,
    "pageSize": 20
  }
}

Ví dụ gọi `resource_query` (aggregate)

json

{
  "name": "resource_query",
  "arguments": {
    "resource": "orders",
    "measures": [
      { "field": "amount", "aggregation": "sum", "alias": "totalAmount" }
    ],
    "dimensions": [
      { "field": "createdAt", "format": "YYYY-MM", "alias": "month" }
    ],
    "orders": [{ "field": "createdAt", "order": "desc" }],
    "limit": 12
  }
}

Hỗ trợ Association Resources

CRUD tools hỗ trợ association resources (nested resources):

json

{
  "name": "resource_list",
  "arguments": {
    "resource": "users.roles",
    "sourceId": 5
  }
}

Đường dẫn tạo ra: users/5/roles:list

Swagger-based Tools

Ngoài CRUD tools, plugin tự động quét Swagger/OpenAPI definitions từ các plugin đã cài để tạo thêm tools chuyên biệt. Các tools này được đặt tên dựa trên resource name và action name trong path template.

Luồng xử lý request

Lưu ý bảo mật

Token kế thừa quyền người dùng: MCP tools thực thi với quyền của Bearer token đi kèm — tạo token với quyền tối thiểu cần thiết
ACL: Endpoint mcp yêu cầu loggedIn — người dùng phải đăng nhập
Internal request: Tool gọi Digiforce API bằng light-my-request (inject nội bộ) — không qua network, nhưng vẫn qua đầy đủ middleware (ACL, validation)
Error handling: Lỗi được trả về dưới dạng MCP error content, không expose stack trace
OAuth2 401: Nếu xác thực thất bại, server trả về WWW-Authenticate header theo RFC chuẩn, giúp AI client tự động refresh token