Chuẩn Model Context Protocol (MCP) chính thức 2026

Tích hợp AI Agent với Cơm Ngon MCP Server

Kết nối trực tiếp các AI Agent bên ngoài (Claude Desktop, Cursor IDE, n8n, AI Agent độc lập) với hệ sinh thái Cơm Ngon để tự động tra cứu báo cáo, đặt cơm, và quản lý nhân sự qua giao thức chuẩn hóa.

Kiến trúc kết nối

Cách AI Agent giao tiếp với Cơm Ngon

1

AI Agent của bạn

Claude Desktop, Cursor IDE, hệ thống n8n hoặc AI Agent tự phát triển gửi lệnh hội thoại tự nhiên của người dùng.

Cốt lõi
2

Cơm Ngon Cloud MCP (Vercel)

Vận hành trực tiếp trên máy chủ đám mây Vercel qua endpoint https://comngon.io.vn/api/mcp, xác thực đa tổ chức (Multi-tenant) qua API Key và gọi hàm SSOT.

3

Supabase Database

Đọc/ghi dữ liệu suất ăn, lịch làm việc, danh sách phòng ban và bảo vệ an toàn bằng Row-Level Security (RLS).

Hướng dẫn cài đặt

Kết nối trong vòng 3 phút

Chọn nền tảng AI bạn đang sử dụng để xem cấu hình mẫu

claude_desktop_config.json
{
  "mcpServers": {
    "com-ngon": {
      "url": "https://comngon.io.vn/api/mcp",
      "headers": {
        "x-api-key": "sk_live_YOUR_API_KEY"
      }
    }
  }
}
☁️ Kết nối đám mây (Cloud Remote MCP Server): AI Agent kết nối trực tiếp đến máy chủ Vercel qua endpoint https://comngon.io.vn/api/mcp mà KHÔNG cần tải mã nguồn hay cài đặt Node.js trên máy tính của bạn.
🔑 Lấy mã API Key: Quản trị viên đăng nhập vào Cơm Ngon > Cài đặt > API Keys để lấy mã bí mật có tiền tố sk_live_... gắn vào header x-api-key.
API Reference

Danh mục 8 Công cụ (Tools)

Tất cả các công cụ đều có tham số được xác thực nghiêm ngặt bằng Zod schema

get_meal_statisticsTra cứu SSOT

Tra cứu số liệu thống kê suất ăn tổng hợp chuẩn Single Source of Truth (tổng suất ăn, lượt nghỉ, khách, tỷ lệ hủy, chi phí, tiền tiết kiệm) cho một tháng cụ thể hoặc khoảng ngày bất kỳ.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
start_datestring (optional)Ngày bắt đầu YYYY-MM-DD (VD: 2026-08-01)
end_datestring (optional)Ngày kết thúc YYYY-MM-DD (VD: 2026-08-31)
monthnumber (optional)Tháng cần tra cứu (1 - 12)
yearnumber (optional)Năm cần tra cứu (VD: 2026)
Mẫu gọi tool
get_meal_statistics({ month: 8, year: 2026 })
Kết quả trả về mẫu (JSON)
BÁO CÁO SUẤT ĂN CƠM NGON (2026-08-01 → 2026-08-31):
- Tổng suất ăn: 1.391 suất
- Suất khách: 0 suất
- Tổng lượt nghỉ ăn: 345 lượt
- Số ngày bếp nấu: 23 ngày
- Tỷ lệ hủy/nghỉ: 19.9%
get_today_summaryHôm nay Realtime

Lấy dữ liệu tổng quan số lượng suất ăn hôm nay theo thời gian thực (số người ăn, nghỉ ăn, suất khách, trạng thái bếp nấu).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
Mẫu gọi tool
get_today_summary({})
Kết quả trả về mẫu (JSON)
☀️ THỐNG KÊ HÔM NAY (2026-09-03):
- Trạng thái bếp: Bếp đang nấu ăn 🍳
- Tổng suất ăn dự kiến: 73 suất
- Số người báo nghỉ: 9 người
- Suất khách đăng ký: 0 suất
get_employees_listNhân sự

Lấy danh sách nhân viên trong doanh nghiệp. Hỗ trợ tìm kiếm theo tên, email, mã nhân viên, lọc theo phòng ban và trạng thái.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
searchstring (optional)Từ khóa tìm kiếm theo họ tên, email hoặc mã nhân viên
departmentstring (optional)Lọc theo phòng ban (VD: Marketing)
statusenum (optional)"active" | "paused" | "resigned" | "all"
limitnumber (optional)Số lượng tối đa cần lấy (mặc định 50)
Mẫu gọi tool
get_employees_list({ search: "Hải", department: "Ban Giám Đốc" })
Kết quả trả về mẫu (JSON)
Tìm thấy 1 nhân sự:
1. Thân Công Hải (haibn@vietvisiontravel.com) - Mã: NV001 - Phòng: Ban Giám Đốc [active]
get_employee_detailHồ sơ nhân sự

Xem thông tin chi tiết một nhân viên (họ tên, email, mã NV, phòng ban, chức vụ, trạng thái làm việc) và lịch sử đăng ký cơm 7 ngày gần nhất.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
querystring (required)Họ tên, email hoặc mã nhân viên cần tra cứu chi tiết
Mẫu gọi tool
get_employee_detail({ query: "Thân Công Hải" })
Kết quả trả về mẫu (JSON)
👤 THÔNG TIN CHI TIẾT NHÂN VIÊN:
- Họ và tên: Thân Công Hải
- Email: haibn@vietvisiontravel.com
- Mã nhân viên: NV001
- Phòng ban: Ban Giám Đốc
- Chức vụ: admin
- Trạng thái: Đang làm việc 🟢
📅 LỊCH SỬ ĐĂNG KÝ CƠM GẦN ĐÂY:
  • 2026-09-03: ✅ ĂN CƠM
  • 2026-09-02: ❌ BÁO NGHỈ (Lý do: Đi gặp đối tác)
get_kitchen_overviewVận hành bếp

Tra cứu tổng quan vận hành bếp: số suất cần nấu hôm nay hoặc một ngày cụ thể, chi tiết suất ăn chính và suất khách.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (optional)Ngày cần kiểm tra YYYY-MM-DD (mặc định hôm nay)
Mẫu gọi tool
get_kitchen_overview({ date: "2026-09-03" })
Kết quả trả về mẫu (JSON)
🍳 TỔNG QUAN BẾP ĂN NGÀY 2026-09-03:
- Trạng thái bếp: Đang nấu ăn
- Số suất ăn chính thức: 73 suất
- Suất khách đặc biệt: 0 suất
- TỔNG CẦN NẤU: 73 suất
get_daily_order_detailsChi tiết suất ăn

Xem danh sách chi tiết ai đăng ký ăn cơm và ai báo nghỉ ăn vào một ngày cụ thể, kèm theo lý do báo nghỉ.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (optional)Ngày cần xem định dạng YYYY-MM-DD
Mẫu gọi tool
get_daily_order_details({ date: "2026-09-03" })
Kết quả trả về mẫu (JSON)
📋 DANH SÁCH CHI TIẾT SUẤT ĂN NGÀY 2026-09-03:
- Ăn cơm: 73 người
- Báo nghỉ: 9 người
🔴 DANH SÁCH BÁO NGHỈ:
  1. Nguyễn Văn A [Sale] - Lý do: Đi tour Hạ Long
  2. Trần Thị B [Kế toán] - Lý do: Làm việc tại nhà
get_guest_meals_listSuất khách

Tra cứu danh sách các đoàn khách đăng ký ăn cơm theo ngày hoặc theo tháng (số lượng suất khách, ghi chú đoàn khách).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (optional)Ngày cụ thể YYYY-MM-DD
monthnumber (optional)Tháng cần lọc
yearnumber (optional)Năm cần lọc
Mẫu gọi tool
get_guest_meals_list({ month: 9, year: 2026 })
Kết quả trả về mẫu (JSON)
🍽️ DANH SÁCH SUẤT ĂN KHÁCH ĐOÀN (1 lượt - Tổng: 5 suất):
1. [ID: abc-123] Ngày 2026-09-05: 5 suất - Ghi chú: "Đoàn đối tác Nhật Bản"
get_cooking_scheduleLịch nấu bếp

Tra cứu lịch hoạt động của bếp ăn trong tháng (những ngày nào bếp nấu ăn, ngày nào bếp nghỉ, ngày lễ và ngày ngoại lệ nấu thêm).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
monthnumber (optional)Tháng cần tra cứu (1 - 12)
yearnumber (optional)Năm cần tra cứu
Mẫu gọi tool
get_cooking_schedule({ month: 9, year: 2026 })
Kết quả trả về mẫu (JSON)
📅 LỊCH VẬN HÀNH BẾP THÁNG 9/2026:
- Lịch nấu mặc định: Thứ 2 đến Thứ 6 hàng tuần.
⚠️ CÁC NGÀY NGOẠI LỆ:
  • 2026-09-02: 🏖️ BẾP NGHỈ ĐỘT XUẤT/LỄ - Lý do: Quốc Khánh 2/9
get_departments_listPhòng ban

Tra cứu danh sách tất cả các phòng ban trong công ty và số lượng nhân sự trực thuộc từng phòng ban.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
Mẫu gọi tool
get_departments_list({})
Kết quả trả về mẫu (JSON)
🏢 DANH SÁCH PHÒNG BAN (6 phòng - Tổng 102 nhân sự):
1. Khối Kinh Doanh: 45 nhân sự
2. Khối Điều Hành Tour: 28 nhân sự
3. Kế Toán & Tài Chính: 12 nhân sự
get_announcementsThông báo

Xem danh sách các thông báo mới nhất từ Ban quản lý hoặc Bếp gửi tới toàn thể công ty.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
limitnumber (optional)Số lượng thông báo cần lấy (mặc định 5)
Mẫu gọi tool
get_announcements({ limit: 3 })
Kết quả trả về mẫu (JSON)
📢 THÔNG BÁO MỚI NHẤT:
1. [URGENT] Thông báo thực đơn đặc biệt Thứ 6 tuần này: Bếp phục vụ bún chả Hà Nội.
update_meal_registrationNghiệp vụ ăn

Cập nhật trực tiếp trạng thái suất ăn của một nhân viên vào một ngày nhất định (đăng ký ăn hoặc hủy cơm).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employee_email_or_codestring (required)Email, mã nhân viên hoặc họ tên
datestring (required)Ngày áp dụng YYYY-MM-DD
statusenum (required)"eating" (ăn cơm) hoặc "not_eating" (hủy cơm)
reasonstring (optional)Lý do thay đổi
Mẫu gọi tool
update_meal_registration({ employee_email_or_code: "Thân Công Hải", date: "2026-09-04", status: "not_eating", reason: "Đi công tác" })
Kết quả trả về mẫu (JSON)
"✅ Đã cập nhật suất ăn ngày 2026-09-04 cho Thân Công Hải: NGHỈ ĂN."
batch_update_meal_registrationNghiệp vụ ăn

Đăng ký ăn hoặc báo nghỉ cơm cho NHIỀU nhân viên cùng lúc vào một ngày cụ thể.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employee_listarray (required)Danh sách họ tên, email hoặc mã nhân viên
datestring (required)Ngày áp dụng YYYY-MM-DD
statusenum (required)"eating" hoặc "not_eating"
reasonstring (optional)Lý do
Mẫu gọi tool
batch_update_meal_registration({ employee_list: ["NV001", "NV002"], date: "2026-09-04", status: "not_eating" })
Kết quả trả về mẫu (JSON)
"📋 KẾT QUẢ CẬP NHẬT HÀNG LOẠT NGÀY 2026-09-04:
✅ Thân Công Hải: Nghỉ ăn
✅ Nguyễn Văn B: Nghỉ ăn"
add_guest_mealsNghiệp vụ bếp

Thêm suất ăn cho khách hoặc đối tác phát sinh vào một ngày cụ thể kèm ghi chú.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (required)Ngày phục vụ khách YYYY-MM-DD
quantitynumber (required)Số lượng suất ăn cần thêm
notestring (optional)Ghi chú đoàn khách
Mẫu gọi tool
add_guest_meals({ date: "2026-09-05", quantity: 5, note: "Đoàn đối tác Nhật Bản" })
Kết quả trả về mẫu (JSON)
"✅ Đã ghi nhận thêm 5 suất khách cho ngày 2026-09-05 [Mã đơn: d123-456]."
delete_guest_mealsNghiệp vụ bếp

Hủy/xóa một đơn suất ăn khách đoàn đã đăng ký trước đó theo mã ID đơn.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
guest_meal_idstring (required)Mã UUID của đơn khách đoàn
Mẫu gọi tool
delete_guest_meals({ guest_meal_id: "d123-456" })
Kết quả trả về mẫu (JSON)
"✅ Đã hủy/xóa thành công đơn suất ăn khách đoàn [ID: d123-456]."
create_employeeNhân sự

Thêm mới một nhân viên vào hệ thống công ty.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
full_namestring (required)Họ và tên đầy đủ
emailstring (required)Email đăng nhập
employee_codestring (optional)Mã nhân viên
departmentstring (optional)Phòng ban
Mẫu gọi tool
create_employee({ full_name: "Lê Văn C", email: "c@company.com", department: "Kinh Doanh" })
Kết quả trả về mẫu (JSON)
"✅ Đã thêm mới nhân viên thành công: Lê Văn C (c@company.com)."
update_employee_statusNhân sự

Thay đổi trạng thái hoạt động nhân viên (active = đang làm việc, paused = tạm dừng cơm, resigned = đã nghỉ việc).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employee_querystring (required)Họ tên, email hoặc mã nhân viên
statusenum (required)"active" | "paused" | "resigned"
Mẫu gọi tool
update_employee_status({ employee_query: "Lê Văn C", status: "paused" })
Kết quả trả về mẫu (JSON)
"✅ Đã cập nhật trạng thái nhân viên Lê Văn C thành: [paused]."
set_cooking_exceptionLịch bếp

Cài đặt ngày ngoại lệ nấu ăn cho bếp (no_cook = bếp nghỉ đột xuất/nghỉ lễ, extra_cook = nấu thêm vào ngày nghỉ cuối tuần).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (required)Ngày áp dụng YYYY-MM-DD
exception_typeenum (required)"no_cook" | "extra_cook"
reasonstring (optional)Lý do ngoại lệ
Mẫu gọi tool
set_cooking_exception({ date: "2026-09-02", exception_type: "no_cook", reason: "Nghỉ lễ Quốc Khánh 2/9" })
Kết quả trả về mẫu (JSON)
"✅ Đã cập nhật ngoại lệ nấu ăn ngày 2026-09-02: BẾP NGHỈ."
delete_cooking_exceptionLịch bếp

Xóa một ngày ngoại lệ nấu ăn của bếp để khôi phục lại lịch nấu ăn mặc định.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
datestring (required)Ngày ngoại lệ cần xóa YYYY-MM-DD
Mẫu gọi tool
delete_cooking_exception({ date: "2026-09-02" })
Kết quả trả về mẫu (JSON)
"✅ Đã xóa ngày ngoại lệ 2026-09-02. Lịch nấu của bếp trở lại bình thường."
send_announcementThông báo

Đăng thông báo mới từ Quản trị viên hoặc Bếp gửi đến toàn thể nhân viên trong công ty.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
titlestring (required)Tiêu đề thông báo
contentstring (required)Nội dung chi tiết thông báo
priorityenum (optional)"normal" | "urgent" | "info"
Mẫu gọi tool
send_announcement({ title: "Đổi giờ ăn trưa", content: "Hôm nay giờ ăn bắt đầu lúc 11h45", priority: "urgent" })
Kết quả trả về mẫu (JSON)
"📢 Đã gửi thông báo mới thành công! - Tiêu đề: Đổi giờ ăn trưa"
update_employee_profileNhân sự

Chỉnh sửa toàn diện hồ sơ nhân sự: họ tên, phòng ban, mã NV, chức vụ (role), chế độ ăn mặc định (eating/not_eating), ghi chú.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employee_querystring (required)Email, mã NV hoặc họ tên
full_namestring (optional)Họ và tên mới
departmentstring (optional)Phòng ban mới
employee_codestring (optional)Mã nhân viên
default_meal_statusenum (optional)"eating" | "not_eating"
roleenum (optional)"employee" | "kitchen_admin" | "manager"
Mẫu gọi tool
update_employee_profile({ employee_query: "c@company.com", department: "Phòng Marketing", role: "manager" })
Kết quả trả về mẫu (JSON)
"✅ Đã cập nhật hồ sơ nhân sự thành công: Lê Văn C - Phòng Marketing - Quyền: manager"
delete_employeeNhân sự

Xóa nhân viên khỏi hệ thống hoặc đánh dấu nghỉ việc (resigned).

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employee_querystring (required)Email, mã NV hoặc họ tên
permanentboolean (optional)true: Xóa hẳn, false: Đánh dấu nghỉ việc (mặc định false)
Mẫu gọi tool
delete_employee({ employee_query: "c@company.com", permanent: false })
Kết quả trả về mẫu (JSON)
"👋 Đã đánh dấu nhân viên Lê Văn C là ĐÃ NGHỈ VIỆC [resigned]."
batch_create_employeesNhân sự

Thêm danh sách nhiều nhân viên mới vào hệ thống công ty cùng lúc.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
employeesarray (required)Mảng các đối tượng [{ full_name, email, department, employee_code }]
Mẫu gọi tool
batch_create_employees({ employees: [{ full_name: "Nguyễn A", email: "a@co.com" }, { full_name: "Trần B", email: "b@co.com" }] })
Kết quả trả về mẫu (JSON)
"👥 KẾT QUẢ THÊM NHÂN SỰ HÀNG LOẠT (2/2 thành công)..."
delete_announcementThông báo

Gỡ bỏ hoặc hủy một thông báo đã đăng trước đó theo mã ID.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
announcement_idstring (required)Mã UUID của thông báo
Mẫu gọi tool
delete_announcement({ announcement_id: "8c35b5a2-..." })
Kết quả trả về mẫu (JSON)
"🗑️ Đã xóa thành công thông báo [ID: 8c35b5a2-...]."
update_company_settingsHệ thống

Cập nhật cấu hình công ty: giờ chốt đăng ký cơm (HH:MM), giờ tự động reset và ngày nấu trong tuần.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
registration_deadlinestring (optional)Giờ chốt cơm (HH:MM)
auto_reset_timestring (optional)Giờ tự động reset cơm ngày mai (HH:MM)
start_cooking_daynumber (optional)Thứ bắt đầu nấu (1=Thứ 2, ..., 6=Thứ 7)
end_cooking_daynumber (optional)Thứ kết thúc nấu (5=Thứ 6, 6=Thứ 7)
Mẫu gọi tool
update_company_settings({ registration_deadline: "09:00", auto_reset_time: "13:30" })
Kết quả trả về mẫu (JSON)
"⚙️ ĐÃ CẬP NHẬT CẤU HÌNH VẬN HÀNH THÀNH CÔNG..."
trigger_daily_meal_resetHệ thống

Kích hoạt lệnh tự động khởi tạo / reset đơn cơm cho ngày mai theo chế độ mặc định của nhân sự.

Tham số đầu vào:
Tên tham sốKiểu dữ liệuMô tả & Chú thích
target_datestring (optional)Ngày cần reset YYYY-MM-DD (mặc định ngày mai)
Mẫu gọi tool
trigger_daily_meal_reset({ target_date: "2026-09-05" })
Kết quả trả về mẫu (JSON)
"🔄 ĐÃ ĐỒNG BỘ ĐƠN CƠM CHO NGÀY 2026-09-05: 102 người, 95 đơn..."