Skip to main content

Integración con Google Workspace

Google Workspace — cómo configurar, instalar y usar la integración con Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides y más) vía MCP. ↑ mercadolibre · tiendanube · ⬆ intro de la sección

Esta guía explica todo el proceso necesario para configurar, instalar y utilizar la integración de Google Workspace en la plataforma. A diferencia de MercadoLibre/TiendaNube (que son APIs REST propias envueltas en un MCP), Google Workspace se sirve con un MCP de terceros (taylorwilsdon/google_workspace_mcp) corriendo en modo "external OAuth provider": valida directamente el Bearer token del usuario contra Google, sin gestionar su propio consentimiento.

1. Arquitectura​

  • Una sola app OAuth de Google para toda la plataforma (credenciales compartidas).
  • Cada usuario vincula su propia cuenta Google desde el Portal (Mis Integraciones → Google Workspace).
  • Los tokens (access + refresh) se guardan por usuario en user-service (sync_data, servicio google), con refresco automático igual que MercadoLibre/TiendaNube.
  • Un único contenedor MCP compartido (infrastructure/mcp_servers/google_workspace) atiende a todos los usuarios; chat-server inyecta el google_access_token del usuario activo como header Authorization: Bearer en cada llamada (credential_source: user_service, ver migración 078_seed_google_workspace_mcp.py).
  • Tools habilitadas: --tool-tier complete — el catálogo completo (Gmail, Drive, Calendar, Docs, Sheets, Chat, Forms, Slides, Tasks, Contacts, Search, Apps Script). Search requiere un motor de Custom Search Engine externo no configurado en este deploy; su tool queda registrada pero fallará si se invoca.

2. Creación de la aplicación en Google Cloud Console​

  1. Ir a console.cloud.google.com y crear/seleccionar un proyecto para integraciones de plataforma.
  2. Pantalla de consentimiento OAuth (APIs y servicios → Pantalla de consentimiento OAuth):
    • Tipo de usuario: Internal (solo cuentas del workspace) o External según el caso.
    • Completar nombre de app, email de soporte, dominios autorizados.
    • Agregar los scopes usados (ver sección 4 — son de lectura/escritura completos porque el MCP expone tools de creación/edición, no solo lectura).
    • Publicar la app cuando esté lista para producción.
  3. Credenciales OAuth (APIs y servicios → Credenciales → Crear credencial → ID de cliente OAuth):
    • Tipo de aplicación: Web application.
    • Authorized redirect URIs: https://<tu-dominio-portal>/oauth/google/callback (y el equivalente local, ej. https://portal.local:8443/oauth/google/callback).
    • Guardar Client ID y Client Secret.
  4. Habilitar APIs (APIs y servicios → Biblioteca): Gmail API, Google Calendar API, Google Drive API, Google Docs API, Google Sheets API, Google Slides API, Google Forms API, Google Tasks API, People API (Contacts), Google Chat API, Apps Script API.

3. Configuración de variables de entorno​

Mismo patrón que MercadoLibre/TiendaNube: credenciales globales en la raíz del repo, ./infra env generate las propaga a cada .env de proyecto.

En .env.secrets:

GLOBAL_GOOGLE_CLIENT_ID=...
GLOBAL_GOOGLE_CLIENT_SECRET=...

En .env:

GLOBAL_GOOGLE_REDIRECT_URI=https://tu-dominio.com/oauth/google/callback

Estas se propagan a:

  • platform/portal/.env → GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI.
  • infrastructure/user-service/.env → mismas claves (usadas para el exchange/refresh del authorization code).
  • infrastructure/mcp_servers/google_workspace/.env → GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET (usadas por el MCP para validar el Bearer token en modo external OAuth provider).

4. Scopes solicitados​

Se piden scopes de lectura/escritura completos por servicio (definidos en platform/portal/ui/src/app/api/admin/google/oauth/start/route.ts), para habilitar todas las tools del MCP:

openid email profile
gmail.modify gmail.send gmail.compose gmail.labels gmail.settings.basic
drive calendar documents spreadsheets presentations
forms.body forms.responses.readonly
tasks contacts
chat.messages chat.spaces

5. Flujo de sincronización del usuario (Portal + user-service)​

  1. Usuario abre el Portal → Mis Integraciones → pulsa Conectar Cuenta en Google Workspace.
  2. Se abre /api/admin/google/oauth/start, que redirige a Google con los scopes de la sección 4 y un state que codifica el user_id.
  3. Google redirige a /oauth/google/callback con el code.
  4. El callback llama a /api/admin/google/sync, que llama a user-service's POST /api/v1/integrations/google/sync.
  5. user-service intercambia el code por access_token/refresh_token contra https://oauth2.googleapis.com/token y los guarda en sync_data bajo el servicio google.
  6. El Portal refresca el estado vía POST /api/admin/subsystems/check (subsystemId: google_workspace) y muestra CONECTADO.

user-service refresca el access_token automáticamente (TTL 3600s, threshold 300s) usando el refresh_token almacenado — igual mecanismo que MercadoLibre/TiendaNube (SyncService._ensure_valid_token).

6. Levantar el MCP de Google Workspace​

cd infrastructure/mcp_servers/google_workspace
cp .env.example .env   # completar MCP_PORT, DOCKER_NETWORK_NAME, GOOGLE_OAUTH_CLIENT_ID/SECRET
../../../infra up mcp_servers/google_workspace

El Dockerfile clona taylorwilsdon/google_workspace_mcp en build time (no hay fuente propia versionada en este repo más allá del Dockerfile). El contenedor corre con:

  • MCP_ENABLE_OAUTH21=true
  • EXTERNAL_OAUTH21_PROVIDER=true — no gestiona su propio consent flow, valida el Bearer recibido.
  • WORKSPACE_MCP_STATELESS_MODE=true — sin escritura a disco.
  • --tool-tier complete — catálogo completo de tools.

7. Registro en chat-server​

El servicio MCP sys-google-workspace está seedeado por migración (infrastructure/chat-server/app/migrations/versions/078_seed_google_workspace_mcp.py), siguiendo el mismo patrón "system" que ThingsBoard/Chatwoot/Store/Infra:

  • URL interna: http://google-workspace-mcp:8000/mcp.
  • required_roles: google, internal-assistant — solo usuarios con el rol google (o el asistente interno) ven este MCP.
  • credential_source: user_service, inyectando google_access_token como header Authorization: Bearer.

8. Checklist de validación​

  1. Usuario A sincroniza su cuenta Google y puede ejecutar tools (ej. search_gmail_messages).
  2. Usuario B sincroniza otra cuenta y ve solo sus propios datos — mismo contenedor MCP, sin cruce de información (el Bearer token por request aísla la sesión).
  3. Si se revoca el acceso desde Google, la próxima llamada falla y el usuario debe re-sincronizar desde el Portal.
  4. Usuarios sin el rol google no ven el MCP en la lista de herramientas disponibles del agente.
  5. docker exec google-workspace-mcp env | grep GOOGLE_OAUTH confirma que las credenciales de la app llegaron al contenedor.

9. Rol google en Zitadel​

required_roles del MCP es ["google", "internal-assistant"] — un usuario necesita el project role google (o internal-assistant) para que el MCP aparezca en su lista de herramientas, aunque ya haya sincronizado su cuenta. Se agrega como cualquier otro project role (ver docs/internal/operations/test-accounts.md para el patrón general de alta de roles vía API de Zitadel).

10. Notas operativas​

  • Mantener pineada la versión del contenedor en el Dockerfile (actualmente clona main con --depth=1; considerar pinnear a un tag/commit si se necesita reproducibilidad estricta).
  • Monitorear errores 401/403/429 en user-service y chat-server (docker logs user-service, ./infra logs chat-server).
  • Si se amplían o reducen scopes, hacerlo revisando el consent screen en Google Cloud Console y coordinando con los usuarios ya sincronizados (deberán re-autorizar).