Trong các nền tảng có kiến trúc hướng sự kiện (event-driven), phần lớn logic nghiệp vụ ở khu vực quản trị không được lộ ra dưới dạng REST endpoint truyền thống, mà được gói lại thành các "sự kiện" (event) có tên riêng, nhận một tham số đầu vào và xử lý. Nó có thể trả về một kết quả đầu ra hoặc không. Vấn đề đặt ra là: một trợ lý AI (hoặc một client bất kỳ) muốn gọi đúng một sự kiện thì phải biết chính xác nó cần gửi những trường dữ liệu nào, kiểu gì, và sẽ nhận lại những gì. Bài viết này giải thích một MCP tool được thiết kế riêng để giải quyết đúng vấn đề đó: tra cứu "lược đồ" (schema) của một sự kiện quản trị theo tên.

Event Schema Là Gì

Event schema là bản mô tả hợp đồng (contract) của một sự kiện trong hệ thống, gồm bốn phần:
  • description — mô tả sự kiện này dùng để làm gì
  • argumentSchema — cấu trúc dữ liệu đầu vào: tên trường, kiểu dữ liệu, trường nào bắt buộc, mô tả, ví dụ giá trị, và có thể lồng nhau nhiều cấp (object chứa object, mảng chứa object...)
  • resultSchema — cấu trúc dữ liệu trả về, có định dạng tương tự argumentSchema
  • examples — một vài ví dụ minh hoạ cách gọi thực tế
Có thể hình dung event schema giống như một bản OpenAPI/JSON Schema thu nhỏ, nhưng dành cho một "sự kiện" thay vì một REST endpoint. Mỗi sự kiện trong hệ thống — kể cả các event handler tuỳ biến do người dùng tự định nghĩa — đều có thể phát sinh ra một schema như vậy, và MCP tool được nói tới trong bài chính là cách để lấy ra bản mô tả đó theo đúng tên sự kiện cần biết.

Vì Sao Cần MCP Tool Này

Nếu không có tool này, một trợ lý AI muốn gọi một sự kiện quản trị chỉ có hai lựa chọn: đoán cấu trúc dữ liệu (dễ sai tên trường, sai kiểu) hoặc đọc trực tiếp mã nguồn (không khả thi với AI không có quyền truy cập source, và tốn ngữ cảnh không cần thiết). MCP tool get_admin_event_schema_by_name giải quyết việc này bằng cách cho phép AI hỏi thẳng hệ thống: "sự kiện tên X có schema như thế nào?" và nhận lại đúng phần mô tả input/output của riêng sự kiện đó — không phải toàn bộ danh mục.
Đây là điểm khác biệt quan trọng so với một tool khác cùng nhóm chỉ trả về link tải toàn bộ schema của mọi sự kiện (vì bản đầy đủ quá lớn để đọc thẳng vào ngữ cảnh của AI). Tool theo tên thì ngược lại: kết quả đủ nhỏ nên được trả thẳng dưới dạng text/JSON trong câu trả lời của tool, sẵn sàng để AI đọc và dùng ngay.

Luồng Hoạt Động Khi Gọi Tool

MCP tool hoạt động qua giao thức JSON-RPC chuẩn của MCP (tools/call). Khi AI gọi tool với tham số eventName, hệ thống tìm handler tương ứng, lấy schema của nó, chuyển thành JSON rồi trả về.
sequenceDiagram
    participant AI as Trợ lý AI (MCP client)
    participant MCP as MCP Server (khu vực quản trị)
    participant QL as Bộ quản lý sự kiện
    participant EV as Sự kiện được yêu cầu

    AI->>MCP: tools/call "get_admin_event_schema_by_name" (eventName)
    MCP->>QL: tìm sự kiện theo eventName
    alt Tìm thấy
        QL->>EV: lấy schema (input/output/mô tả/ví dụ)
        EV-->>QL: EventSchema
        QL-->>MCP: EventSchema
        MCP-->>AI: trả JSON schema (isError = false)
    else Không tìm thấy
        MCP-->>AI: "No event schema found for eventName=..." (isError = true)
    else eventName trống
        MCP-->>AI: "eventName is required" (isError = true)
    end
Kết quả trả về được đóng gói theo đúng chuẩn nội dung tool call của MCP: một khối content dạng text (để hiển thị/đọc trực tiếp), và một khối structuredContent.schema chứa cùng nội dung JSON đó ở dạng có cấu trúc, tiện cho client xử lý theo chương trình thay vì chỉ đọc chuỗi text.

Biết Tên Sự Kiện Trước Khi Tra Schema

eventName là tham số bắt buộc, vậy trước tiên AI cần biết tên sự kiện cần tra. Trong bộ tool MCP còn có một tool liệt kê tất cả các sự kiện/handler hiện có (kèm trạng thái, ví dụ đã publish hay còn nháp), giúp AI khám phá tên sự kiện phù hợp trước khi hỏi chi tiết. Luồng làm việc điển hình của một trợ lý AI khi cần gọi một sự kiện quản trị thường đi qua ba bước:
flowchart TD
    A[Người dùng muốn AI thực hiện một thao tác quản trị] --> B{Đã biết tên sự kiện cần gọi?}
    B -- Chưa --> C[Gọi tool liệt kê danh sách sự kiện]
    C --> D[Chọn ra eventName phù hợp với yêu cầu]
    B -- Rồi --> D
    D --> E["Gọi get_admin_event_schema_by_name(eventName)"]
    E --> F{Có schema?}
    F -- Có --> G[Đọc argumentSchema và resultSchema]
    G --> H[Soạn dữ liệu đầu vào đúng định dạng]
    H --> I[Gọi sự kiện thật với dữ liệu đã soạn]
    F -- Không --> J[Báo người dùng: tên sự kiện không tồn tại]
Việc tách thành hai bước "liệt kê" rồi "tra chi tiết theo tên" giúp AI không phải tải toàn bộ danh mục sự kiện chỉ để lấy schema của một sự kiện duy nhất — vừa nhanh, vừa tiết kiệm ngữ cảnh.

Cấu Trúc Input/Output Của Tool

Đầu vào (inputSchema):
TrườngKiểuBắt buộcÝ nghĩa
eventNamestringcóTên chính xác của sự kiện cần lấy schema
Đầu ra (outputSchema): một object gồm trường schema kiểu string, chứa nội dung JSON mô tả input/output của sự kiện được yêu cầu.
Ví dụ minh hoạ nội dung trả về (mang tính minh hoạ, không phải một sự kiện thật của hệ thống):
{
  "description": "Cập nhật thông tin hồ sơ người dùng.",
  "argumentSchema": {
    "name": "argument",
    "dataType": "object",
    "required": true,
    "fields": [
      {
        "name": "userId",
        "dataType": "long",
        "required": true,
        "description": "ID người dùng cần cập nhật"
      },
      {
        "name": "displayName",
        "dataType": "string",
        "required": false,
        "description": "Tên hiển thị mới",
        "example": "Nguyen Van A"
      }
    ]
  },
  "resultSchema": {
    "name": "result",
    "dataType": "boolean",
    "description": "true nếu cập nhật thành công"
  },
  "examples": [
    "{"userId": 123, "displayName": "Nguyen Van A"}"
  ]
}
Nhờ cấu trúc fields lồng nhau, schema có thể mô tả cả những sự kiện có tham số phức tạp (object chứa object, mảng phần tử object...), không chỉ các kiểu dữ liệu đơn giản.

Cách Gõ Prompt Để Sử Dụng Tool

Khi trợ lý AI đã được kết nối vào MCP server của khu vực quản trị, người dùng không cần gọi tool theo cú pháp kỹ thuật — chỉ cần diễn đạt mục đích bằng ngôn ngữ tự nhiên, AI sẽ tự quyết định gọi đúng tool. Một vài kiểu prompt hiệu quả:
Khi đã biết tên sự kiện:
> "Cho tôi xem schema của sự kiện `update_user_profile`."
> "Sự kiện `delete_post` nhận vào những tham số gì và trả về gì?"
Khi chưa biết tên sự kiện, chỉ biết mục đích:
> "Tôi muốn cập nhật thông tin người dùng, hãy tìm sự kiện phù hợp và cho tôi biết cần truyền dữ liệu gì."
Với prompt dạng này, AI cần tự kết hợp tool liệt kê sự kiện với tool tra schema theo tên — nên diễn đạt rõ mục tiêu cuối cùng (ví dụ "để tôi có thể gọi nó") để AI biết cần lấy đủ cả input lẫn output, không chỉ dừng ở tên sự kiện.
Khi muốn AI dùng schema để soạn sẵn dữ liệu gọi:
> "Lấy schema của sự kiện `create_order`, sau đó soạn giúp tôi một request mẫu để tạo đơn hàng cho khách hàng có ID 456, số lượng 2 sản phẩm mã SKU-001."
Prompt kiểu này tận dụng đúng giá trị của tool: AI tra schema trước, đối chiếu đúng tên trường/kiểu dữ liệu/trường bắt buộc, rồi mới soạn payload — giảm hẳn tình trạng AI "đoán" tên trường sai.
Khi tên sự kiện không tồn tại:
Nếu AI báo không tìm thấy schema, nên yêu cầu AI liệt kê lại danh sách sự kiện hiện có thay vì đoán một tên khác:
> "Không tìm thấy sự kiện đó, hãy liệt kê các sự kiện đang có liên quan đến đơn hàng."

Điều Kiện Sử Dụng Và Bảo Mật

Tool này chỉ hoạt động trong phạm vi phiên làm việc quản trị đã xác thực — mọi lời gọi tới MCP server đều đi kèm access token quản trị hợp lệ, và tính năng AI Tools (MCP) cần được bật cho tài khoản/hệ thống trước khi các tool này khả dụng. Nói cách khác, đây không phải một endpoint công khai không cần đăng nhập; nó nằm trong ranh giới quyền hạn của tài khoản quản trị đang gọi.

Giới Hạn Cần Lưu Ý

  • Tool chỉ trả về schema của một sự kiện tại một thời điểm, dựa trên tên chính xác — không hỗ trợ tìm theo từ khoá gần đúng hay wildcard.
  • Nếu eventName bị bỏ trống hoặc rỗng, tool trả lỗi ngay mà không thử tra cứu.
  • Nếu sự kiện không tồn tại, tool trả về thông báo lỗi rõ ràng thay vì trả JSON rỗng hay gây nhầm lẫn.
  • Đây là công cụ tra cứu, không phải công cụ gọi sự kiện — sau khi có schema, việc thực thi sự kiện thật là một bước/tool riêng.

Kết Luận

MCP tool tra schema sự kiện theo tên là một mảnh ghép nhỏ nhưng quan trọng để AI có thể tương tác an toàn và chính xác với các sự kiện quản trị: thay vì đoán mò cấu trúc dữ liệu, AI tra hợp đồng dữ liệu ngay trước khi hành động. Kết hợp với tool liệt kê danh sách sự kiện, đây trở thành một quy trình hai bước gọn gàng — khám phá tên sự kiện, rồi tra đúng schema của nó — giúp giảm sai sót khi AI thay người dùng thao tác trên hệ thống quản trị.