Skip to main content

Google Workspace MCP

Status

Owner: TBD · Status: draft · Canonical source: flezi.app.frontend.main/src/components/mcp-servers/google/, flezi.app.api.backend/app/integrations/google/

Who is this for?​

Administrators configuring organization OAuth and members who want Agents to use Gmail, Google Calendar, or Google Drive with the permissions of their own Google account.

How it works​

The Google Workspace connector uses OAuth 2.0 + PKCE. OAuth app credentials are managed at organization level; access tokens are stored and used per connector + user. A member who receives a shared connector must still authorize their own Google account.

Do not share tokens

Do not upload or share another user's token.json. A token belongs to one account and connector; disconnecting your account does not disconnect another member.

Administrator setup​

  1. Create a Web application OAuth Client in Google Cloud Console.

  2. In the Google connector App Credentials tab, upload client_secret.json or configure credentials using the deployment procedure.

  3. Read the Authorized Redirect URI from the backend status response/UI and register that exact URI in Google Cloud Console. It has this form:

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

    <api-host> is the API host, not necessarily the SPA host. Do not derive the callback from browser origin when the hosts differ.

  4. Share the connector with a Workspace or Organization when other members need it.

Writing credentials requires System Admin, Org Admin, or Workspace Admin. Regular members can view status, authorize an account, and use shared tools.

Connect a personal account​

  1. Open MCP Servers and select the Google connector.
  2. Open Account & OAuth.
  3. Click Sign in with Google and approve the displayed scopes.
  4. Return to Flezi Galaxy, verify Connected, and run Test Connection.
  5. Use Re-authenticate Account when the token expires or permissions change.

The Google connector also supports direct token.json upload for the selected connector. The file must be valid JSON containing token or access_token; it remains scoped to the current user and server.

Tools​

The built-in Google Workspace connector currently registers seven tools:

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

Main limits: Gmail search returns at most 25 results; Calendar lists at most 100 events; Drive returns at most 100 files and reads at most 100,000 characters. Unsupported Drive file types return metadata and a web URL when available.

Endpoint scope

The backend can map scopes for other hosted Google MCP endpoints (for example Chat or People), but those are not built-in tools of the local flezi-mcp service. Check the selected connector's Tools Explorer.

Disconnect and troubleshoot​

  • Needs OAuth: Authorize the current account before testing.
  • 401: The access token is expired or invalid; re-authenticate.
  • 403: A scope is missing or an API is disabled in Google Cloud Console.
  • No tools: Check provider, MCP URL, and account status, then run Test Connection again.
  • OAuth returns without Connected: Only backend oauth_result=success confirms a successful callback.