---
name: iblai-connect-google-workspace
description: "Read and write Google Workspace data through the Google Workspace APIs (Drive API v3, Gmail API v1, Calendar API v3, Admin SDK Directory API) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Google Workspace data, or to set up a Google Workspace MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Google Workspace connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/google-workspace — not part of the iblai/vibe repository. Checked against Google's documentation on October 20, 2026; test it against your own Google Workspace setup before you rely on it.

Google Workspace holds an organization's Gmail mailboxes, Google Drive files and shared drives, Docs, Sheets and Slides, Google Calendar events, Chat spaces, and the user and group directory managed in the Admin console.

## Auth & conventions

- **API:** Google Workspace APIs (Drive API v3, Gmail API v1, Calendar API v3, Admin SDK Directory API) (REST). Separate REST APIs per product: Drive files and permissions, Gmail messages, drafts and labels, Calendar calendars and events, and Admin SDK Directory users, groups and org units for administrators.
- **Access:** Public, self-serve. Create a Google Cloud project, enable each API and configure the OAuth consent screen. Domain-wide delegation for a service account must be authorized by a Workspace super admin in the Admin console.
- **Auth:** OAuth 2.0 authorization code; Service account; Service account with domain-wide delegation; API key (public data only). OAuth client IDs access a user's data with consent. Service accounts use a key pair; with domain-wide delegation they act for users across the domain on admin-granted scopes without per-user consent. API keys only reach public data.
- **Limits:** Drive API: 1,000,000 quota units per minute per project and 325,000 per minute per user per project; files.list costs 100 units. Over-limit returns 403 User rate limit exceeded or 429; use truncated exponential backoff.
- Keep Google Workspace credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Drive files** — GET https://www.googleapis.com/drive/v3/files with a q filter; pageSize up to 1000, pageToken paging. Includes trashed files unless filtered.
- **Gmail messages** — Read messages and threads for a user, addressed as users/{userId} where userId can be me.
- **Calendar events** — List and read events at https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events.
- **Directory users and groups** — Admin SDK Directory API at https://admin.googleapis.com/admin/directory/v1/users; administrators only.

## Writes

- **Send email** — POST https://gmail.googleapis.com/gmail/v1/users/{userId}/messages/send; needs gmail.send, gmail.compose, gmail.modify or full mail scope. **Confirm with the user first.**
- **Calendar events** — POST .../calendars/{calendarId}/events; sendUpdates=all or externalOnly emails guests. **Confirm with the user first.**
- **Drive files** — Create, upload, update and share files; files.update costs 50 quota units.
- **Directory users** — Create, update and delete user accounts; deleted users can be restored within 20 days. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Google publishes an official MCP server, Google Workspace MCP servers (https://developers.google.com/workspace/guides/configure-mcp-servers). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Google Workspace supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Find the signed MSA for Acme in Drive and summarize the renewal terms"
- "Draft a reply to the latest email from finance about the Q3 budget"
- "Find a 30-minute slot next week when the whole product team is free"
- "List Workspace users who were added in the last 30 days"

## Guardrails

- Mail, files and calendars hold confidential business data and personal data; content may include regulated records (health, financial, student) depending on the organization.
- Request the narrowest Google Workspace scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Create access credentials: https://developers.google.com/workspace/guides/create-credentials
- Configure the Google Workspace MCP servers: https://developers.google.com/workspace/guides/configure-mcp-servers
- Drive API usage limits: https://developers.google.com/workspace/drive/api/guides/limits
- Google Workspace MCP servers: https://developers.google.com/workspace/guides/configure-mcp-servers
- This connector on ibl.ai: https://ibl.ai/developer/connectors/google-workspace
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections