Chuyển tới nội dung chính

Hướng dẫn Tích hợp Luồng xác thực (Authentication & Consent)

Tài liệu này hướng dẫn Nhà phát triển (NPT) cách triển khai luồng xác thực và xin quyền người dùng (User Consent) khi tích hợp công cụ vào hệ sinh thái MCP.

1. Tổng quan luồng vận hành​

Sơ đồ tổng quan

Quá trình giao tiếp giữa người dùng, hệ thống V-AI và MCP Server của bên thứ ba được chia thành 4 giai đoạn chính:

Giai đoạn 1: Khởi tạo và Tiếp nhận yêu cầu​

  • Người dùng: Khởi tạo yêu cầu trên ứng dụng V-AI (Host App).
  • AI Agent: Đóng gói yêu cầu gọi công cụ (Tool Request) kèm theo thông tin ngữ cảnh người dùng và gửi đến MCP Gateway.

MCP Gateway đóng vai trò "gatekeeper" để đảm bảo quyền riêng tư:

  • Kiểm tra trạng thái: Gateway xác định công cụ này có yêu cầu xác thực hay không (dựa trên cấu hình app-config.json).
  • Trường hợp chưa có quyền (Chưa Consent):
    • Gateway trả về mã lỗi 403 CONSENT_REQUIRED.
    • Host App hiển thị Popup Consent yêu cầu người dùng cho phép chia sẻ dữ liệu.
    • Sau khi người dùng bấm "Kết nối", V-AI App gửi lệnh xác nhận (Submit Consent Grant) để Gateway lưu trạng thái.
  • Trường hợp đã có quyền: Hệ thống tự động bỏ qua bước này và chuyển sang thực thi gọi Tool.

Giai đoạn 3: Xác thực với 3rd Party MCP Server​

Tùy vào cấu hình NPT thiết lập trên V-Console, MCP Gateway thực hiện kết nối sang hệ thống của bạn qua một trong hai chế độ:

  • Chế độ 1: API Key (Custom Header)
    • Gateway đính kèm khóa API tĩnh vào header (ví dụ: X-Api-Key).
    • MCP Server của NPT xác thực key này để xử lý yêu cầu.
  • Chế độ 2: OAuth Client Credentials
    • Cấp Token: Gateway gửi yêu cầu sang Auth Server của bên thứ ba để lấy Access Token ngắn hạn.
    • Truy cập: Gateway sử dụng Token này (Bearer Token) để gửi kèm Tool Call Request tới MCP Server.
    • Định danh: MCP Server validate và định danh người dùng thông qua token này.

Giai đoạn 4: Xử lý và Trả kết quả​

  • Thực thi: 3rd Party MCP Server thực hiện nghiệp vụ và trả kết quả định dạng JSON-RPC.
  • Chuẩn hóa: MCP Gateway kiểm tra tính an toàn của dữ liệu theo chính sách nền tảng.
  • Hiển thị: Kết quả được trả về Host App để render thành văn bản hoặc Web Widget nội tuyến.

2. Cấu hình Kỹ thuật​

Cấu hình file app-config.json​

NPT cần khai báo các công cụ bắt buộc phải qua luồng xác thực.

Ví dụ:

{
  "appId": "vinpearl",
  "auth": [
    {
      "tool_name": "book_hotel"
    },
    {
      "tool_name": "get_booking_info"
    }
  ]
}

Cấu hình trên V-Console​

  • Authentication: Chọn Custom Header (API Key) hoặc Custom OAuth.
    • Đối với Custom Header: NPT nhập thêm thông tin key và value để MCP Gateway đính kèm và gửi sang AI App.
    • Đối với Custom OAuth: NPT nhập thêm các trường thông tin cho luồng OAuth.
  • Consent Message: Nội dung hiển thị trên màn hình xin quyền của người dùng.
  • Endpoint: Địa chỉ MCP Server và Auth Server (nếu dùng OAuth).