Giao diện

Câu hỏi thường gặp (FAQ) — MCP Server ​

Cài đặt và cấu hình ​

AI agent nào hỗ trợ MCP? ​

Các AI agent/IDE hỗ trợ MCP protocol bao gồm:

AgentHỗ trợ
Claude DesktopCó (built-in)
Cursor IDECó (MCP integration)
VS Code + ContinueCó (qua extension)
Custom agentsCó (dùng @modelcontextprotocol/sdk)

Bất kỳ client nào hỗ trợ Streamable HTTP Transport đều kết nối được với Digiforce MCP Server.

Cần cài thêm plugin nào không? ​

Plugin MCP Server hoạt động độc lập. Tuy nhiên, để có thêm tools:

  • Các plugin có Swagger/OpenAPI definitions sẽ tự động expose thêm tools
  • Plugin idp-oauth (tuỳ chọn) để hỗ trợ OAuth2 authentication chuẩn

URL endpoint MCP là gì? ​

{API_BASE_PATH}/mcp

Mặc định: https://your-domain/api/mcp

Giá trị API_BASE_PATH được đọc từ biến môi trường (mặc định: /api).

Sử dụng ​

Có bao nhiêu tools mặc định? ​

Plugin luôn tạo 6 CRUD tools tổng quát:

  1. resource_list — Liệt kê records
  2. resource_get — Lấy record theo ID
  3. resource_create — Tạo record
  4. resource_update — Cập nhật record
  5. resource_destroy — Xoá record
  6. resource_query — Aggregate query

Ngoài ra, các tools bổ sung được tạo từ Swagger definitions (số lượng phụ thuộc vào plugins đã cài).

Làm sao giới hạn tools expose cho AI? ​

Gửi header x-mcp-packages kèm danh sách package name muốn expose:

x-mcp-packages: plugin-data-source-main, plugin-users

Chỉ Swagger tools từ các package liệt kê mới được trả về. CRUD tools tổng quát luôn có mặt vì chúng không phụ thuộc Swagger.

Dữ liệu trả về có format như thế nào? ​

Kết quả tool call được trả về dạng MCP content:

json
{
  "content": [
    {
      "type": "text",
      "text": "{\"data\": [...], \"meta\": {\"count\": 42}}"
    }
  ],
  "isError": false
}

Dữ liệu được serialize thành JSON string. AI agent sẽ tự parse và xử lý.

AI có thể truy vấn aggregate (thống kê) không? ​

Có. Dùng tool resource_query với measures, dimensions, orders:

json
{
  "resource": "orders",
  "measures": [
    { "field": "amount", "aggregation": "sum" },
    { "field": "id", "aggregation": "count" }
  ],
  "dimensions": [
    { "field": "status" }
  ]
}

Kết quả trả về dạng bảng thống kê theo group.

Bảo mật ​

Dữ liệu có an toàn không? ​

MCP Server kế thừa toàn bộ hệ thống bảo mật Digiforce:

  • ACL: Mỗi tool call đi qua ACL middleware — AI chỉ truy cập được dữ liệu mà user có quyền
  • Token scope: Token kế thừa quyền của người dùng — tạo user riêng cho AI với quyền tối thiểu
  • Internal inject: Request được thực thi nội bộ (không qua network), nhưng vẫn qua đầy đủ middleware

Cảnh báo

AI có thể thực hiện create, update, destroy nếu token có đủ quyền. Nên tạo API token/user riêng cho AI với quyền chỉ đọc nếu không cần ghi dữ liệu.

Có audit log không? ​

Plugin ghi lỗi qua this.log.error. Để có audit log chi tiết, bạn có thể:

  • Bật LOGGER_LEVEL=debug để log tất cả request
  • Sử dụng plugin audit-logs (nếu có) để tracking thay đổi dữ liệu

Lỗi thường gặp ​

AI agent không kết nối được? ​

Kiểm tra theo thứ tự:

  1. URL đúng chưa? Endpoint là {domain}/api/mcp (POST method)
  2. Token hợp lệ? Thử gọi API Digiforce khác với cùng token
  3. Server accessible? Đảm bảo AI agent có thể truy cập server qua internet (hoặc VPN)
  4. CORS: Nếu gọi từ browser, kiểm tra cấu hình CORS
  5. Plugin đã bật? Kiểm tra plugin-mcp-server trong Plugin Manager

Lỗi 401 "Authentication required"? ​

Token không hợp lệ hoặc đã hết hạn. Nếu dùng OAuth2:

  • Kiểm tra response header WWW-Authenticate chứa resource_metadata URL
  • Client cần refresh token theo OAuth2 flow

Nếu dùng Bearer token:

  • Kiểm tra token chưa hết hạn
  • Kiểm tra user còn active

Tool call trả về "Tool not found"? ​

Tool name không tồn tại. Gọi ListTools trước để xem danh sách tools có sẵn. Lưu ý:

  • Tool name được format từ resource/action path (lowercase, underscore)
  • CRUD tools luôn có tên: resource_list, resource_get, resource_create, resource_update, resource_destroy, resource_query

Response trả về lỗi 500 từ tool call? ​

Lỗi xảy ra khi thực thi action trên Digiforce. Kiểm tra:

  • Missing params: Tool yêu cầu resource (bắt buộc) và các tham số tuỳ action
  • Invalid filter: JSON filter không đúng format Digiforce
  • Permission denied: User không có quyền thực hiện action trên collection đó
  • Xem server log để biết chi tiết lỗi