Chuyển tới nội dung chính

Google Workspace MCP

Trạng thái

Owner: TBD · Trạng thái: draft · Nguồn chuẩn: flezi.app.frontend.main/src/components/mcp-servers/google/, flezi.app.api.backend/app/integrations/google/

Dành cho ai​

Quản trị viên cấu hình OAuth của tổ chức và thành viên muốn cho Agent sử dụng Gmail, Google Calendar hoặc Google Drive theo quyền tài khoản Google của mình.

Cách hoạt động​

Google Workspace connector dùng OAuth 2.0 + PKCE. OAuth app credentials được quản lý ở cấp tổ chức; access token được lưu và sử dụng riêng theo cặp connector + user. Thành viên được chia sẻ connector vẫn phải authorize tài khoản Google của chính mình.

Không dùng chung token

Không upload hoặc chia sẻ token.json của người khác. Token được cấp cho một tài khoản và connector cụ thể; disconnect tài khoản của bạn không ngắt tài khoản của thành viên khác.

Thiết lập cho quản trị viên​

  1. Tạo OAuth Client loại Web application trong Google Cloud Console.

  2. Trong màn hình App Credentials của Google connector, upload client_secret.json hoặc cấu hình credentials theo hướng dẫn của deployment.

  3. Lấy Authorized Redirect URI từ response trạng thái của Backend/UI và đăng ký chính xác URI đó trong Google Cloud Console. URI có dạng:

    https://<api-host>/api/v1/integrations/google/callback

    <api-host> là host API, không phải mặc định host của SPA. Không tự suy ra callback từ origin của trình duyệt nếu hai host khác nhau.

  4. Chia sẻ connector cho Workspace/Organization nếu thành viên khác cần sử dụng.

Quyền ghi credentials app yêu cầu System Admin, Org Admin hoặc Workspace Admin. Thành viên thông thường chỉ xem trạng thái, authorize tài khoản và dùng Tools được chia sẻ.

Kết nối tài khoản cá nhân​

  1. Mở MCP Servers → chọn Google connector.
  2. Chọn tab Account & OAuth.
  3. Nhấn Sign in with Google và chấp thuận các scopes được hiển thị.
  4. Quay lại Flezi Galaxy; kiểm tra trạng thái Connected rồi chạy Test Connection.
  5. Có thể dùng Re-authenticate Account khi token hết hạn hoặc quyền đã thay đổi.

Google connector cũng hỗ trợ upload trực tiếp token.json cho connector đang chọn. File phải là JSON hợp lệ và chứa token hoặc access_token; cách này vẫn lưu token theo user hiện tại, không biến token thành credential dùng chung.

Tools​

Connector Google Workspace dựng sẵn hiện đăng ký 7 tools:

  • Gmail: gmail_search, gmail_read_message.
  • Calendar: calendar_list_events, calendar_get_event, calendar_create_event.
  • Drive: drive_search, drive_read_file.

Giới hạn chính: Gmail search tối đa 25 kết quả; Calendar tối đa 100 sự kiện; Drive tối đa 100 file và nội dung đọc trực tiếp tối đa 100.000 ký tự. File Drive không hỗ trợ đọc trực tiếp sẽ trả về metadata và web URL nếu có.

Phạm vi endpoint

Backend có thể map scopes cho các Google MCP endpoint hosted khác (ví dụ Chat hoặc People), nhưng điều đó không có nghĩa các tools này đã có trong built-in flezi-mcp service. Hãy kiểm tra Tools Explorer của connector cụ thể.

Ngắt kết nối và xử lý lỗi​

  • Needs OAuth: authorize tài khoản hiện tại trước khi test.
  • 401: access token hết hạn hoặc không hợp lệ; re-authenticate.
  • 403: thiếu scope hoặc API chưa bật trong Google Cloud Console.
  • Không thấy Tools: kiểm tra provider, URL MCP và trạng thái account; sau đó chạy lại Test Connection.
  • OAuth quay lại nhưng không Connected: chỉ kết quả oauth_result=success từ Backend mới xác nhận callback thành công.

Liên quan​