MCP cho trợ lý AI

Máy chủ Model Context Protocol của Nextfarm cho mọi trợ lý AI hỗ trợ MCP (ChatGPT, Claude, Copilot, Cursor, Gemini, Grok…) hay trợ lý riêng đọc dữ liệu trại. Hai cách nối: chỉ cần URL (người dùng đăng nhập NextFarm, chọn trại, tick quyền — OAuth 2.1) hoặc API key cho máy.

	Địa chỉ
Production	`https://mcp.nextfarm.vn/mcp`
Sandbox	`https://mcp-dev.nextfarm.vn/mcp`

Cách 1 — Chỉ cần URL (OAuth)

Dán https://mcp.nextfarm.vn/mcp vào trợ lý AI bạn dùng — ChatGPT (Apps & Connectors, Developer mode), claude.ai / Claude Code (Connectors), Copilot Studio (Tools › Model Context Protocol), Cursor, Gemini CLI, Grok (Connectors › Custom), VS Code… (cấu hình từng client ở hub AI). Trợ lý mở trang đăng nhập NextFarm → chọn trại → tick quyền → Cho phép. Trợ lý chỉ làm được những gì người đăng nhập đang được làm trong trại; Ghi mặc định không tick, chủ trại có thể tắt hẳn. Ngắt ở app › Hệ thống › Ứng dụng › Ứng dụng AI ⇒ lượt kế tiếp bị từ chối.

Thêm máy chủ MCP / connector trong trợ lý AI bạn dùng
  URL: https://mcp.nextfarm.vn/mcp
→ Connect → đăng nhập NextFarm → chọn trại → Cho phép

Scope OAuth	Cho phép	Ghi?
`gis:read`	Bản đồ, thửa, vùng, mùa vụ, nông dân
`iot:read`	Thiết bị, số đo cảm biến, cảnh báo
`harvest:read`	Thu hoạch, truy xuất, tem QR, chứng nhận, giá
`office:read`	Sổ nông trại, công việc, lịch, luật tự động hoá
`reports:read`	Xem và xuất báo cáo

Chuẩn: OAuth 2.1 + PKCE (S256), Protected Resource Metadata (RFC 9728), Authorization Server Metadata (RFC 8414), Dynamic Client Registration (RFC 7591) hoặc Client ID Metadata Document, Resource Indicators (RFC 8707). Access token 1 giờ, refresh token xoay vòng. Thiếu scope ⇒ 403 insufficient_scope (trợ lý xin thêm). Token của trợ lý không bao giờ đi tiếp vào API: máy chủ MCP đổi lấy token uỷ quyền ngắn hạn theo Token Exchange (RFC 8693), giới hạn đúng quyền bạn đã đồng ý.

Cách 2 — API key (máy, n8n, máy chủ của bạn)

Tạo khoá

Ở Hệ thống › API key, tạo một khoá riêng cho trợ lý với scope chỉ đọc cần thiết.

Nối trợ lý

{
  "url": "https://mcp.nextfarm.vn/mcp",
  "transport": "streamable-http",
  "headers": { "Authorization": "Bearer nfk_…" }
}

Chưa chắc chạy? Kiểm kết nối ngay ở hub AI, hoặc mở MCP Tester (đăng nhập OAuth được). Trợ lý trên web (ChatGPT, claude.ai…) không nhận API key — dùng Cách 1.

Công cụ

Công cụ	Làm gì	Scope
`farm_overview`	Diện tích thửa gộp theo hộ, vùng hoặc cây trồng: số hộ, số thửa, tổng diện tích (ha), số thửa chưa có ranh giới. Xếp theo diện tích giảm dần.	`gis:read`
`gis_crop_types_list`	Danh mục loại cây trồng của trại: mã, tên, nhóm. Dùng mã loại cây để lọc thửa, mùa vụ, sản lượng.	`gis:read`
`gis_farmers_list`	Hộ nông dân / thành viên của vùng nguyên liệu: tên, vùng, nhóm hộ, loại thành viên. Lọc theo vùng, nhóm, loại.	`gis:read`
`gis_parcels_get`	Một thửa: tên, mã, diện tích, vùng, chủ hộ, cây đang trồng, trạng thái.	`gis:read`
`gis_parcels_list`	Danh sách thửa của trại: mã, diện tích (ha), vùng, chủ hộ, cây đang trồng, trạng thái. Lọc theo vùng, cây, trạng thái.	`gis:read`
`gis_search`	Tìm thửa, mùa vụ, hộ nông dân và vùng theo từ khoá; nhóm nào ngoài quyền của khoá thì trả rỗng.	`gis:read`
`gis_seasons_groups`	Gộp các vụ cùng cây, cùng tên vụ trên nhiều thửa trong một năm (vd Lúa · Đông Xuân): số thửa, tổng diện tích, ngày trồng sớm/muộn nhất.	`gis:read`
`gis_seasons_list`	Mùa vụ theo một thửa (lịch sử canh tác) hoặc theo năm: cây, tên vụ, ngày trồng, ngày dự kiến thu, trạng thái. Cần ít nhất một trong hai: thửa hoặc năm.	`gis:read`
`gis_zones_stats`	Số thửa và tổng diện tích (ha) của một vùng.	`gis:read`
`certification_expiring`	Chứng nhận (VietGAP, GlobalGAP, hữu cơ…) sắp hết hạn hoặc đã hết hạn, xếp theo ngày hết hạn tăng dần.	`harvest:read`
`harvest_phi_active`	Các thửa, ao, chuồng đang trong thời gian cách ly thuốc bảo vệ thực vật hoặc ngưng thuốc thú y: ngày sớm nhất được thu và lần dùng thuốc đang giữ cách ly.	`harvest:read`
`harvest_record_list`	Phiếu khai thu hoạch: thửa, cây, sản lượng khai (kg), trạng thái (draft · confirmed · verified · collected · void), ngày thu, lô truy xuất.	`harvest:read`
`harvest_search`	Tìm phiếu thu hoạch, tem QR và chứng nhận theo từ khoá (mã phiếu, mã tem, tên chứng nhận).	`harvest:read`
`harvest_summary`	Sản lượng đã thu (chỉ phiếu đã xác nhận) gộp theo hộ, vùng, cây hoặc thửa, trong khoảng ngày thu hoạch. Xếp theo tổng kg giảm dần.	`harvest:read`
`harvest_trace_get`	Một lô truy xuất: nhật ký canh tác, chứng nhận, ảnh — đúng nội dung người mua thấy khi quét tem.	`harvest:read`
`harvest_trace_list`	Các lô truy xuất nguồn gốc đã phát hành của trại: thửa, vùng, sản phẩm, chứng nhận, ngày thu, hộ trồng, số công đoạn.	`harvest:read`
`phi_status`	Thửa còn trong thời gian cách ly thuốc không, ngày sớm nhất được thu, lần dùng thuốc đang giữ cách ly.	`harvest:read`
`iot_alerts_list`	Cảnh báo cảm biến vượt ngưỡng: thiết bị, chỉ số, giá trị, ngưỡng, mức độ, trạng thái xử lý.	`iot:read`
`iot_command_status`	Các lệnh gần nhất gửi xuống một bộ điều khiển: loại lệnh, trạng thái, lúc gửi, thiết bị đã nhận chưa.	`iot:read`
`iot_device_list`	Thiết bị IoT của trại: tên, loại, đang trực tuyến hay mất kết nối, lần cuối báo về. Lọc theo trạng thái, thửa, vùng.	`iot:read`
`iot_devices_search`	Tìm thiết bị theo tên hoặc mã.	`iot:read`
`iot_irrigation_outputs`	Đầu ra tưới của một bộ điều khiển: loại (bơm, van khu, châm phân), số thứ tự và tên người dùng đặt (vd 'Lô A').	`iot:read`
`iot_readings_history`	Lịch sử số đo theo thiết bị hoặc vùng trong một khoảng thời gian, mới nhất trước.	`iot:read`
`iot_readings_latest`	Số đo mới nhất của từng cảm biến (nhiệt độ, độ ẩm, EC, pH…) cho cả trại hoặc một vùng.	`iot:read`
`iot_schedule_upcoming`	Các lượt tưới sắp chạy theo lịch: bộ điều khiển, giờ chạy, thời lượng (giây), van, đã hoãn hay đã chạy.	`iot:read`
`office_automations_list`	Các luật tự động hoá của trại: tên, trạng thái, kiểu kích hoạt, lần chạy gần nhất.	`office:read`
`office_books_fields`	Các cột của một bảng: tên, kiểu dữ liệu, tuỳ chọn — dùng để đọc đúng giá trị từng dòng.	`office:read`
`office_books_list`	Các sổ nông trại tự dựng của trại (nhật ký, kho, chi phí…): tên, mô tả, số bảng.	`office:read`
`office_books_records`	Đọc các dòng của một bảng trong sổ, phân trang; giá trị theo mã cột.	`office:read`
`office_books_tables`	Các bảng trong một sổ nông trại.	`office:read`
`report_catalog`	Các báo cáo có sẵn của trại: mã, tên, nhóm và số khối dữ liệu bạn được xem.	`reports:read`
`report_query`	Chạy một báo cáo theo mã trong khoảng ngày: chỉ số tổng, chuỗi theo thời gian, phân rã, bảng. Thiếu ngày thì lấy 30 ngày gần nhất.	`reports:read`

farm_overview — Tổng hợp diện tích thửa

Diện tích thửa gộp theo hộ, vùng hoặc cây trồng: số hộ, số thửa, tổng diện tích (ha), số thửa chưa có ranh giới. Xếp theo diện tích giảm dần.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "crop_type_id": {
      "description": "Chỉ một loại cây",
      "format": "uuid",
      "type": "string"
    },
    "group_by": {
      "description": "Gộp theo: owner (hộ) · zone (vùng) · crop (cây trồng)",
      "type": "string"
    },
    "page_size": {
      "description": "Số nhóm tối đa",
      "type": "integer"
    },
    "status": {
      "description": "Trạng thái thửa",
      "type": "string"
    },
    "zone_id": {
      "description": "Chỉ một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "group_by": "zone"
}

gis_crop_types_list — Loại cây trồng

Danh mục loại cây trồng của trại: mã, tên, nhóm. Dùng mã loại cây để lọc thửa, mùa vụ, sản lượng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "description": "Nhóm cây (vd lúa, cây ăn quả)",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

gis_farmers_list — Danh sách hộ

Hộ nông dân / thành viên của vùng nguyên liệu: tên, vùng, nhóm hộ, loại thành viên. Lọc theo vùng, nhóm, loại.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "groupId": {
      "description": "Chỉ một nhóm hộ",
      "format": "uuid",
      "type": "string"
    },
    "memberType": {
      "description": "Loại thành viên",
      "type": "string"
    },
    "pageSize": {
      "description": "Số dòng tối đa",
      "type": "integer"
    },
    "zoneId": {
      "description": "Chỉ một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

gis_parcels_get — Chi tiết một thửa

Một thửa: tên, mã, diện tích, vùng, chủ hộ, cây đang trồng, trạng thái.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Mã thửa (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "id": "0190a3c2-5b1e-7c3d-8e4f-000000000001"
}

gis_parcels_list — Danh sách thửa

Danh sách thửa của trại: mã, diện tích (ha), vùng, chủ hộ, cây đang trồng, trạng thái. Lọc theo vùng, cây, trạng thái.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "crop_type_id": {
      "description": "Chỉ một loại cây",
      "format": "uuid",
      "type": "string"
    },
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "status": {
      "description": "Trạng thái thửa",
      "type": "string"
    },
    "zone_id": {
      "description": "Chỉ một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "page": 1,
  "page_size": 50
}

gis_search — Tìm thửa, vùng, hộ, mùa vụ

Tìm thửa, mùa vụ, hộ nông dân và vùng theo từ khoá; nhóm nào ngoài quyền của khoá thì trả rỗng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "description": "Số kết quả tối đa mỗi nhóm",
      "type": "integer"
    },
    "q": {
      "description": "Từ khoá, không dấu cũng được",
      "type": "string"
    }
  },
  "required": [
    "q"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "q": "A-12"
}

gis_seasons_groups — Nhóm vụ trong năm

Gộp các vụ cùng cây, cùng tên vụ trên nhiều thửa trong một năm (vd Lúa · Đông Xuân): số thửa, tổng diện tích, ngày trồng sớm/muộn nhất.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "branchId": {
      "description": "Chỉ một chi nhánh / hợp tác xã",
      "format": "uuid",
      "type": "string"
    },
    "year": {
      "description": "Năm",
      "type": "integer"
    }
  },
  "required": [
    "year"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "year": 2026
}

gis_seasons_list — Mùa vụ

Mùa vụ theo một thửa (lịch sử canh tác) hoặc theo năm: cây, tên vụ, ngày trồng, ngày dự kiến thu, trạng thái. Cần ít nhất một trong hai: thửa hoặc năm.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "parcelId": {
      "description": "Mã thửa",
      "format": "uuid",
      "type": "string"
    },
    "year": {
      "description": "Năm (vd 2026)",
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "year": 2026
}

gis_zones_stats — Thống kê vùng

Số thửa và tổng diện tích (ha) của một vùng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Mã vùng (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

certification_expiring — Chứng nhận sắp hết hạn

Chứng nhận (VietGAP, GlobalGAP, hữu cơ…) sắp hết hạn hoặc đã hết hạn, xếp theo ngày hết hạn tăng dần.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "include_expired": {
      "description": "Gồm cả chứng nhận đã hết hạn",
      "type": "boolean"
    },
    "within_days": {
      "description": "Hết hạn trong bao nhiêu ngày tới (mặc định 30)",
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "within_days": 60
}

harvest_phi_active — Thửa đang cách ly thuốc

Các thửa, ao, chuồng đang trong thời gian cách ly thuốc bảo vệ thực vật hoặc ngưng thuốc thú y: ngày sớm nhất được thu và lần dùng thuốc đang giữ cách ly.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "on": {
      "description": "Ngày xét (yyyy-MM-dd, mặc định hôm nay)",
      "format": "date",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

harvest_record_list — Phiếu thu hoạch

Phiếu khai thu hoạch: thửa, cây, sản lượng khai (kg), trạng thái (draft · confirmed · verified · collected · void), ngày thu, lô truy xuất.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "status": {
      "description": "Lọc theo trạng thái",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "status": "confirmed"
}

harvest_search — Tìm thu hoạch, tem, chứng nhận

Tìm phiếu thu hoạch, tem QR và chứng nhận theo từ khoá (mã phiếu, mã tem, tên chứng nhận).

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "description": "Số kết quả tối đa mỗi nhóm",
      "type": "integer"
    },
    "q": {
      "description": "Từ khoá",
      "type": "string"
    }
  },
  "required": [
    "q"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "q": "VietGAP"
}

harvest_summary — Tổng hợp sản lượng

Sản lượng đã thu (chỉ phiếu đã xác nhận) gộp theo hộ, vùng, cây hoặc thửa, trong khoảng ngày thu hoạch. Xếp theo tổng kg giảm dần.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "crop_type_id": {
      "description": "Chỉ một loại cây",
      "format": "uuid",
      "type": "string"
    },
    "from": {
      "description": "Từ ngày thu (yyyy-MM-dd)",
      "format": "date",
      "type": "string"
    },
    "group_by": {
      "description": "parcel · crop · zone · owner",
      "type": "string"
    },
    "to": {
      "description": "Đến ngày thu (yyyy-MM-dd)",
      "format": "date",
      "type": "string"
    },
    "zone_id": {
      "description": "Chỉ một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "from": "2026-10-01",
  "group_by": "crop",
  "to": "2026-10-31"
}

harvest_trace_get — Chi tiết lô truy xuất

Một lô truy xuất: nhật ký canh tác, chứng nhận, ảnh — đúng nội dung người mua thấy khi quét tem.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Mã lô truy xuất (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

harvest_trace_list — Lô truy xuất

Các lô truy xuất nguồn gốc đã phát hành của trại: thửa, vùng, sản phẩm, chứng nhận, ngày thu, hộ trồng, số công đoạn.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

phi_status — Thời gian cách ly của một thửa

Thửa còn trong thời gian cách ly thuốc không, ngày sớm nhất được thu, lần dùng thuốc đang giữ cách ly.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "on": {
      "description": "Ngày xét (yyyy-MM-dd, mặc định hôm nay)",
      "format": "date",
      "type": "string"
    },
    "parcel_id": {
      "description": "Mã thửa (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "parcel_id"
  ],
  "type": "object"
}

iot_alerts_list — Cảnh báo cảm biến

Cảnh báo cảm biến vượt ngưỡng: thiết bị, chỉ số, giá trị, ngưỡng, mức độ, trạng thái xử lý.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "device_id": {
      "description": "Một thiết bị",
      "format": "uuid",
      "type": "string"
    },
    "from": {
      "description": "Từ",
      "format": "date",
      "type": "string"
    },
    "page": {
      "description": "Trang",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "severity": {
      "description": "Mức độ",
      "type": "string"
    },
    "status": {
      "description": "Trạng thái (vd triggered, acknowledged, resolved)",
      "type": "string"
    },
    "to": {
      "description": "Đến",
      "format": "date",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "status": "triggered"
}

iot_command_status — Lệnh gửi xuống thiết bị

Các lệnh gần nhất gửi xuống một bộ điều khiển: loại lệnh, trạng thái, lúc gửi, thiết bị đã nhận chưa.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "device_id": {
      "description": "Mã bộ điều khiển (UUID)",
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "description": "Số lệnh (tối đa 20)",
      "type": "integer"
    }
  },
  "required": [
    "device_id"
  ],
  "type": "object"
}

iot_device_list — Thiết bị IoT

Thiết bị IoT của trại: tên, loại, đang trực tuyến hay mất kết nối, lần cuối báo về. Lọc theo trạng thái, thửa, vùng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "parcel_id": {
      "description": "Chỉ thiết bị của một thửa",
      "format": "uuid",
      "type": "string"
    },
    "status": {
      "description": "online · offline · active · inactive · maintenance",
      "type": "string"
    },
    "zone_id": {
      "description": "Chỉ thiết bị của một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "status": "offline"
}

iot_devices_search — Tìm thiết bị

Tìm thiết bị theo tên hoặc mã.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "description": "Số kết quả tối đa",
      "type": "integer"
    },
    "q": {
      "description": "Từ khoá",
      "type": "string"
    }
  },
  "required": [
    "q"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "q": "NK2"
}

iot_irrigation_outputs — Van và bơm của bộ điều khiển

Đầu ra tưới của một bộ điều khiển: loại (bơm, van khu, châm phân), số thứ tự và tên người dùng đặt (vd 'Lô A').

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "device_id": {
      "description": "Mã bộ điều khiển (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "device_id"
  ],
  "type": "object"
}

iot_readings_history — Lịch sử số đo

Lịch sử số đo theo thiết bị hoặc vùng trong một khoảng thời gian, mới nhất trước.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "device_id": {
      "description": "Một thiết bị",
      "format": "uuid",
      "type": "string"
    },
    "from": {
      "description": "Từ thời điểm (ISO 8601)",
      "format": "date",
      "type": "string"
    },
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang (tối đa 500)",
      "type": "integer"
    },
    "to": {
      "description": "Đến thời điểm (ISO 8601)",
      "format": "date",
      "type": "string"
    },
    "zone_id": {
      "description": "Một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "from": "2026-10-27",
  "to": "2026-10-28"
}

iot_readings_latest — Số đo mới nhất

Số đo mới nhất của từng cảm biến (nhiệt độ, độ ẩm, EC, pH…) cho cả trại hoặc một vùng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "zone_id": {
      "description": "Chỉ cảm biến của một vùng",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

iot_schedule_upcoming — Lịch tưới sắp chạy

Các lượt tưới sắp chạy theo lịch: bộ điều khiển, giờ chạy, thời lượng (giây), van, đã hoãn hay đã chạy.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "days": {
      "description": "Số ngày tới (1–7)",
      "type": "integer"
    },
    "device_id": {
      "description": "Chỉ một bộ điều khiển",
      "format": "uuid",
      "type": "string"
    },
    "from": {
      "description": "Từ ngày (yyyy-MM-dd, mặc định hôm nay)",
      "format": "date",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Ví dụ đối số

{
  "days": 2
}

office_automations_list — Luật tự động

Các luật tự động hoá của trại: tên, trạng thái, kiểu kích hoạt, lần chạy gần nhất.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "search": {
      "description": "Từ khoá",
      "type": "string"
    },
    "status": {
      "description": "Trạng thái",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

office_books_fields — Cột của bảng

Các cột của một bảng: tên, kiểu dữ liệu, tuỳ chọn — dùng để đọc đúng giá trị từng dòng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "table_id": {
      "description": "Mã bảng (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "table_id"
  ],
  "type": "object"
}

office_books_list — Sổ nông trại

Các sổ nông trại tự dựng của trại (nhật ký, kho, chi phí…): tên, mô tả, số bảng.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "search": {
      "description": "Từ khoá",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

office_books_records — Dòng của bảng

Đọc các dòng của một bảng trong sổ, phân trang; giá trị theo mã cột.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "page": {
      "description": "Trang, từ 1",
      "type": "integer"
    },
    "page_size": {
      "description": "Số dòng mỗi trang",
      "type": "integer"
    },
    "table_id": {
      "description": "Mã bảng (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "table_id"
  ],
  "type": "object"
}

office_books_tables — Bảng trong sổ

Các bảng trong một sổ nông trại.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "app_id": {
      "description": "Mã sổ (UUID)",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "app_id"
  ],
  "type": "object"
}

report_catalog — Danh mục báo cáo

Các báo cáo có sẵn của trại: mã, tên, nhóm và số khối dữ liệu bạn được xem.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

report_query — Chạy báo cáo

Chạy một báo cáo theo mã trong khoảng ngày: chỉ số tổng, chuỗi theo thời gian, phân rã, bảng. Thiếu ngày thì lấy 30 ngày gần nhất.

Tham số (JSON Schema)

{
  "additionalProperties": false,
  "properties": {
    "code": {
      "description": "Mã báo cáo (vd SX-01, lấy từ danh mục báo cáo)",
      "type": "string"
    },
    "from": {
      "description": "Từ ngày (yyyy-MM-dd)",
      "format": "date",
      "type": "string"
    },
    "grain": {
      "description": "Độ chia thời gian: day · week · month · quarter · year",
      "type": "string"
    },
    "to": {
      "description": "Đến ngày (yyyy-MM-dd)",
      "format": "date",
      "type": "string"
    }
  },
  "required": [
    "code"
  ],
  "type": "object"
}

Ví dụ đối số

{
  "code": "SX-01",
  "from": "2026-10-01",
  "grain": "week",
  "to": "2026-10-28"
}

Không có công cụ điều khiển thiết bị. Khoá thiếu scope cho một công cụ thì công cụ trả lời rõ "khoá thiếu scope (cần …)" để trợ lý nói lại với bạn, thay vì đoán.

Máy chủ không giữ trạng thái và không lưu khoá: mỗi yêu cầu dùng đúng khoá bạn gửi, mọi luật scope áp như gọi API trực tiếp.

Gỡ lỗi MCP

Hiện tượng	Sửa
401 ở bước initialize	Key sai / thu hồi / hết hạn, hoặc dán key sandbox vào prod — tạo key mới trong app.
tools/list rỗng	Key không có scope khớp — sửa scopes ở Hệ thống › API key.
406 / 415	Client thiếu Accept: application/json, text/event-stream hoặc Content-Type.
405 khi GET	Máy chủ không giữ session (không có luồng SSE GET) — chỉ dùng POST.
429	Vượt 600 lượt/phút của key — giảm tần suất.
Trợ lý AI báo "không kết nối được"	OAuth chưa lên — dùng client nhận API key.

Bảng đầy đủ và kiểm trực tiếp: MCP Tester →

Luật bảo mật đầy đủ cho đối tác: Bảo mật →