MCP Server (Model Context Protocol) là cổng giúp các trợ lý AI bên ngoài như Claude, ChatGPT, Microsoft Copilot, Claude Code, VS Code, Cursor làm việc trực tiếp với dữ liệu 1Office của bạn. Sau khi kết nối, bạn có thể nhờ trợ lý AI:
Trợ lý AI chỉ làm được những gì chính bạn làm được trên 1Office. Nó dùng đúng tài khoản và phân quyền của bạn, không có quyền nào cao hơn.
| Địa chỉ MCP (URL) | https://Ví dụ: https://congty.1office.vn/ai-mcp |
| Giao thức | Streamable HTTP (JSON-RPC 2.0, method POST) |
| Đăng nhập | OAuth 2.0 + PKCE. Trợ lý AI tự mở màn hình đăng nhập 1Office, bạn chỉ cần đăng nhập và bấm Đồng ý. |
| Quyền (scope) | openid, offline_access, mcp |
| Giới hạn | Tối đa 60 lần gọi tool mỗi phút cho mỗi người dùng trên mỗi ứng dụng AI. Vượt mức thì trợ lý nhận lỗi "Quá nhiều lời gọi tool" và chỉ cần thử lại sau ít phút. |
Mẹo: mở https:// bằng trình duyệt để xem server đang hoạt động và danh sách tool hiện có.
ai_disabled).Ứng dụng AI không thuộc danh sách tin cậy ở trên thì quản trị viên phải tạo ứng dụng thủ công trong Ứng dụng SSO › Thêm mới: nhập tên, Redirect URI do ứng dụng AI cung cấp và chọn scope mcp, offline_access. Sau đó gửi Client ID / Client secret cho người cần kết nối. Secret chỉ hiện một lần ngay sau khi tạo.
Ở mọi trợ lý, bước cuối đều giống nhau: một cửa sổ đăng nhập 1Office hiện ra, bạn đăng nhập rồi bấm Đồng ý cấp quyền.
https://congty.1office.vn/ai-mcp.claude mcp add --transport http 1office https://congty.1office.vn/ai-mcpTrong Claude Code, gõ /mcp, chọn 1office rồi chọn Authenticate. Trình duyệt sẽ mở màn hình đăng nhập 1Office.
Tạo file .vscode/mcp.json trong dự án (hoặc mở lệnh MCP: Add Server):
{
"servers": {
"1office": {
"type": "http",
"url": "https://congty.1office.vn/ai-mcp"
}
}
}Bấm Start phía trên khai báo server rồi đăng nhập khi được hỏi.
Thêm vào ~/.cursor/mcp.json (hoặc .cursor/mcp.json trong dự án):
{
"mcpServers": {
"1office": { "url": "https://congty.1office.vn/ai-mcp" }
}
}Trong phần cài đặt Apps & Connectors (cần bật chế độ nhà phát triển nếu tài khoản yêu cầu), tạo connector mới, dán URL MCP và chọn xác thực OAuth.
Thêm công cụ dạng Model Context Protocol cho agent, dán URL MCP, chọn xác thực OAuth 2.0 (tự đăng ký động). Nếu Copilot yêu cầu nhập tay Client ID/secret, nhờ quản trị viên tạo ứng dụng như hướng dẫn ở mục 3 với Redirect URL do Copilot cung cấp.
Lưu ý: tên menu của các trợ lý bên ngoài có thể thay đổi theo phiên bản của hãng. Nếu không tìm thấy, hãy tìm mục "MCP", "Connectors" hoặc "Custom tools" trong phần cài đặt.
| Nhóm | Tool tiêu biểu | Dùng để |
|---|---|---|
| Tra cứu dữ liệu | list_models, get_model_detail, list_records, query_records, get_record_detail, resolve_lookup |
Tìm đối tượng (công việc, khách hàng…), lọc, gom nhóm, đếm, xem chi tiết bản ghi. |
| Thao tác | describe_action, do_action, prepare_action, process_step |
Tạo, sửa, duyệt, chuyển trạng thái, làm bước quy trình. prepare_action chỉ soạn sẵn form để bạn tự kiểm rồi bấm. |
| Trao đổi | post_comment, get_comments, send_chat_message, send_chat_file, get_chat_history |
Bình luận vào bản ghi, nhắn tin và gửi tệp trong Chat. |
| Tệp | get_file, attach_file, transcribe_file |
Tải tệp đính kèm, đính tệp vào bản ghi, chuyển ghi âm cuộc họp/cuộc gọi thành chữ. |
| Lương & chấm công | get_wage_workbook, trace_wage, aggregate_wage, validate_wage_formula, get_attendance_workbook, trace_attendance |
Đọc bảng lương/bảng công đã tính, giải thích một con số, tổng hợp theo nhiều người × nhiều tháng, kiểm công thức lương. |
| CRM | find_duplicate_leads, find_similar_deals |
Kiểm lead trùng, so cơ hội với các cơ hội đã thắng/thua trước đó. |
| Bảo hiểm (1-IVAN) | diagnose_ivan_unit, trace_ivan_premium, trace_ivan_subscribe |
Tra lỗi giao dịch BHXH điện tử, mức đóng, gói dịch vụ. |
| Chẩn đoán | diagnose_record_access, diagnose_model_access, diagnose_notification, diagnose_mail_delivery, diagnose_filter_result, diagnose_action_preconditions, diagnose_lookup_resolution |
Giải thích vì sao không xem được, không nhận thông báo/email, lọc ra 0 kết quả, không bấm được nút. |
Một số tool chỉ dành cho Nhân sự số (AI Agent) hoặc người quản lý, nên danh sách bạn thấy có thể ngắn hơn bảng trên tuỳ phân quyền.
| Hiện tượng | Nguyên nhân / cách xử lý |
|---|---|
| "Incompatible auth server: does not support dynamic client registration" | Công ty đã tắt "Trợ lý AI tự kết nối". Nhờ quản trị viên bật lại (mục 3), hoặc tạo ứng dụng thủ công rồi nhập Client ID vào trợ lý. |
| "Ứng dụng này không nằm trong danh sách trợ lý AI được phép tự kết nối" | Trợ lý AI dùng Redirect URI lạ. Quản trị viên tạo ứng dụng thủ công với đúng Redirect URI đó. |
| "Quản trị đã tắt kết nối cho …" | Quản trị viên đã tắt loại trợ lý này trong Ứng dụng SSO. |
Lỗi 403 ai_disabled |
AI Agents đang tắt ở Cài đặt › Tích hợp. |
| 401 "Token OAuth không hợp lệ, đã hết hạn hoặc ứng dụng đã bị gỡ" | Bạn đã gỡ quyền, hoặc ứng dụng đã bị xoá. Kết nối lại (Claude Code: /mcp › Authenticate). |
| 403 "Token OAuth thiếu scope mcp" | Ứng dụng tạo thủ công chưa chọn scope mcp. Quản trị viên sửa ứng dụng, sau đó kết nối lại. |
| "Quá nhiều lời gọi tool, thử lại sau ít phút" | Đã vượt 60 lần gọi/phút. Chờ khoảng một phút rồi thử lại, hoặc yêu cầu trợ lý gom bớt truy vấn. |
| Trợ lý báo không thấy dữ liệu | Có thể bạn không có quyền xem. Hãy hỏi "chẩn đoán vì sao tôi không xem được bản ghi …", trợ lý sẽ dùng tool diagnose_record_access. |