Guide: Google Workspace

The Google Workspace integration gives your agents access to Gmail, Calendar, Drive, Sheets, Contacts, and Tasks through a managed MCP server. Authentication is handled by Flapjack's OAuth flow with incremental consent — users only authorize the services they enable.

Supported Services

Service	Tool Prefix	Capabilities
Gmail	gmail_*	Read, send, draft, and modify emails
Calendar	calendar_*	Manage events and check availability
Drive	drive_*	Search and manage files
Sheets	sheets_*	Read and write spreadsheets
Contacts	contacts_*	Search and manage contacts
Tasks	tasks_*	Manage task lists

Setup

1. Connect Google Workspace (Org-Level)

1. Go to flapjack.chat → MCP Servers
2. Click Connect on the "Google Workspace" tile
3. Authorize the base scopes (openid, email, profile) in the Google consent popup
4. The MCP server status changes to Connected

2. Enable Services Per Agent

1. Open an agent's Settings → MCP Servers
2. Attach the Google Workspace MCP
3. Toggle individual services (e.g. Gmail, Calendar)
4. If the required OAuth scopes haven't been granted yet, an incremental consent popup opens — only the new scopes are requested
5. After consent, the service's tools become available to the agent

Per-Service Toggle API

# Check enabled services and granted scopes
curl https://api.flapjack.dev/api/agents/{agentId}/mcps/{mcpId}/services?verify=1 \
  -H "Authorization: Bearer <supabase-jwt>"

# Enable Gmail for this agent
curl -X PATCH https://api.flapjack.dev/api/agents/{agentId}/mcps/{mcpId}/services \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"enableService": "gmail"}'

# Disable Calendar for this agent
curl -X PATCH https://api.flapjack.dev/api/agents/{agentId}/mcps/{mcpId}/services \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"disableService": "calendar"}'

If additional scopes are needed, the PATCH response includes needsConsent: true and consentScopes. To complete the consent flow, call the managed OAuth start endpoint with the missing scopes:

curl -X POST https://api.flapjack.dev/api/mcps/managed-oauth/start \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"provider": "google-workspace", "additionalScopes": ["https://www.googleapis.com/auth/gmail.readonly", "..."]}'

This returns { "authorizationUrl": "https://accounts.google.com/..." } — redirect the user there to grant the new scopes.

How Tool Filtering Works

When an agent has Google Workspace attached with specific services enabled:

1. Flapjack resolves the enabled services to tool prefixes (e.g. gmail → gmail_*)
2. These prefixes are passed to the runtime as allowed_tool_prefixes
3. The MCP client only surfaces tools matching those prefixes
4. If no services are enabled, the MCP is skipped entirely

OAuth & Security

Feature	Detail
PKCE	SHA-256 code challenge on every flow
Incremental consent	Only new scopes are requested when enabling additional services
Token encryption	AES-256-GCM at rest in mcp_credentials
Auto-refresh	Tokens refreshed 2 minutes before expiry
Scope tracking	granted_scopes column tracks what's been authorized
External revocation detection	?verify=1 re-checks against Google's tokeninfo endpoint

Disconnecting

curl -X POST https://api.flapjack.dev/api/mcps/managed-oauth/disconnect \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"provider": "google-workspace"}'

Clears OAuth tokens and resets all agent service toggles for the Google Workspace MCP. The provider field is required.

Next Steps

• MCP: OAuth — general OAuth flow
• MCP: Connecting Servers — adding MCP servers
• API: MCP Servers — MCP management endpoints