MCP — kết nối một tác nhân AI bên ngoài với Omniscol

Tác nhân làm được những gì

Tác nhân MCP hoạt động rất tốt với những câu hỏi tra cứu mà dữ liệu đã có sẵn trong Omniscol:

• “Cho tôi tỷ lệ sử dụng phòng học so với giờ mở cửa trong tuần này.”
• “Tìm giúp tôi một phòng học còn trống vào ba ngày thứ Hai của tháng Mười, trên cùng một khung giờ 2 tiếng.”
• “Trần Văn Nam đã dạy bao nhiêu giờ trong năm học hiện tại?”
• “Hôm nay có những tiết học Toán nào?”
• “Liệt kê những giáo viên đã dạy chưa tới 70% số giờ làm việc của mình trong học kỳ này.”

Những yêu cầu như vậy thường phải kết hợp nhiều công cụ: thời khóa biểu, các trang tổng quan thống kê, thời gian rảnh được tính ra, hồ sơ giáo viên. Tác nhân điều phối các lệnh gọi rồi diễn đạt câu trả lời bằng ngôn ngữ tự nhiên.

Những công cụ được mở

Máy chủ MCP dựng các công cụ của mình từ những tuyến API Omniscol được cho phép dùng với MCP. Những tuyến bị bỏ qua một cách rõ ràng, và một số mô-đun kỹ thuật (chẳng hạn các mô-đun liên quan tới việc xác thực người dùng), sẽ không trở thành công cụ. Vì vậy danh sách phản ánh phần API được mở cho MCP, chứ không phải toàn bộ bên trong của ứng dụng. Dù vậy đó vẫn là một phần rất lớn. Hơn nữa, có một số tuyến dành riêng cho MCP mà chính Omniscol không dùng đến. Đó là trường hợp của các công cụ tìm kiếm nâng cao, giúp Omniscol tra một đoạn văn bản tự do chỉ tên một thực thể (“giáo viên Trần Văn Nam”, “lớp 10A1”) ra mã định danh kỹ thuật của thực thể đó, rồi dùng mã này để truy vấn dữ liệu thật chính xác. Đó cũng là trường hợp của những công cụ phức tạp mà Omniscol không có giao diện đồ họa tương ứng, bởi chúng hợp với việc ra lệnh bằng câu chữ hơn: chẳng hạn việc tìm mức sử dụng và thời gian rảnh của một thực thể (“tìm giúp tôi một phòng học còn trống 2 tiếng buổi chiều trong 3 ngày thứ Hai liên tiếp”, “có giáo viên Toán nào rảnh 3 tiếng trong tuần của ngày 14 tháng Mười không?”).

Các công cụ bao quát nhiều mảng, đáng chú ý là:

• mô-đun Quản trị (người dùng, môn học, năm học, thông số),
• mô-đun Quản lý thời khóa biểu (cấu hình, cơ sở, phòng học, lớp, tiết học),
• mô-đun Thời khóa biểu (lịch giảng dạy, trang tổng quan, tìm kiếm),
• mô-đun Quản lý vắng mặt (khai báo, thống kê),
• tìm kiếm toàn cục.

Những tuyến chỉ đọc là phù hợp nhất cho cách dùng theo kiểu tác nhân. Trong danh mục vẫn có thể có một số thao tác ghi, tùy quyền của mã thông báo và tùy API sẵn có, nhưng chúng phải được giám sát: một yêu cầu làm thay đổi nhiều đối tượng nghiệp vụ cần được một người dùng kiểm chứng trước khi được coi là đáng tin.

Bật máy chủ MCP

Máy chủ MCP có sẵn trên các tài khoản Premium. Mọi thứ đều bắt đầu từ màn hình MCP, mở từ mô-đun Quản trị bằng Cấu hình: màn hình này hiển thị URL của máy chủ theo phạm vi bạn chọn (toàn bộ hoặc giới hạn ở một mô-đun) và cung cấp sẵn các phần cấu hình cho ứng dụng khách của bạn, chép là dùng được ngay.

Cách xác thực chuẩn của MCP là OAuth2. Một ứng dụng khách tương thích (như Claude) chỉ cần kết nối tới URL của máy chủ, tự tìm thấy ở đó phần cấu hình OAuth2 của tài khoản, rồi người dùng chấp thuận quyền truy cập qua một màn hình đồng ý: ngoài URL ra thì không phải cung cấp gì thêm. Phạm vi được cấp đi theo quyền của tài khoản và các giới hạn hiển thị của tài khoản đó. Máy chủ OAuth2 của Omniscol, màn hình quản lý ứng dụng khách và chi tiết về sự đồng ý được mô tả ở OAuth2 / OIDC (nhà cung cấp).

Với một ứng dụng khách không hỗ trợ OAuth2, cũng chính màn hình đó sinh ra một mã thông báo (khóa API, ngày hết hạn, người dùng liên kết tùy chọn, quyền ghi phải tích chọn) rồi đưa ra sẵn các định dạng hữu ích theo từng trường hợp, dán là dùng được ngay: tiêu đề Authorization: Bearer, URL kèm mã thông báo, khối cấu hình Claude Desktop (chế độ miễn phí) và lệnh chạy proxy cục bộ. Mã thông báo dựa trên hệ thống khóa được mô tả trong API Omniscol.

Thực hành tốt về bảo mật

• Xác thực OAuth2 — tiện hơn và nên ưu tiên khi tác nhân của bạn hỗ trợ (Claude bản trả phí).
• Mã thông báo riêng cho AI — hãy tạo một mã thông báo có nhãn dễ hiểu (Tác nhân AI — Claude desktop) để thu hồi được khi cần.
• Phạm vi tối thiểu — với một mã thông báo API, chỉ chọn những điểm truy cập API thật sự cần. Với một mã thông báo OAuth, hãy giới hạn các phạm vi (scope) đúng theo nhu cầu thực tế.
• Nhật ký hoạt động (logs) — một lệnh gọi sẽ xuất hiện trong nhật ký gắn với mã thông báo khi tuyến liên quan có ghi nhật ký. Nhật ký ghi lại lệnh gọi; nó không giữ chi tiết dữ liệu trả về, cũng không giữ nội dung đủ để phát lại yêu cầu.
• Giới hạn hiển thị — tác nhân chỉ thấy những gì Omniscol trả về cho nó. Nếu bạn đã đặt các giới hạn hiển thị chặt chẽ cho vai trò của mã thông báo, chúng vẫn được áp dụng.