Curso
Introduction to Google Workspace with Gemini
30 min
2.6K
Agentes de IA são extremamente poderosos, mas muitas vezes têm uma falha básica: eles ficam desconectados de onde o trabalho realmente acontece no dia a dia — seus e-mails, sua agenda e seus documentos. Sem acesso aos seus dados em tempo real, um LLM é só um gerador de ideias muito eloquente.
Neste tutorial, vou mostrar como aproximar modelos de IA dos dados da sua empresa configurando o servidor MCP do Google Workspace, entendendo os controles de segurança mais recentes e criando um assistente automatizado.
Ao final, você será capaz de:
- Entender a arquitetura do Model Context Protocol (MCP) aplicado ao Google Workspace.
- Configurar os controles de OAuth e o acesso às APIs necessários no Google Cloud.
- Testar a conectividade usando o Gemini CLI e o Google Antigravity.
- Criar um assistente de IA corporativo em Python com o Google ADK que consiga ler e-mails, checar sua agenda e rascunhar documentos em um único ciclo de raciocínio.
Pré-requisitos
- Um projeto no Google Cloud com faturamento habilitado.
- Conhecimentos básicos de Python e REST APIs.
- Uma conta do Google Workspace.
O que é o servidor MCP do Google Workspace?
O servidor MCP do Google Workspace é uma implementação padronizada do Model Context Protocol (MCP) que permite que qualquer cliente de IA compatível (como Claude Desktop, Gemini CLI ou agentes personalizados) interaja com segurança com os apps do Google Workspace.
Em vez de os desenvolvedores escreverem wrappers REST específicos para Gmail, Google Docs, Drive e Calendar a cada novo projeto de IA, o servidor MCP expõe esses recursos como "ferramentas" padronizadas que o LLM entende nativamente.
Recomendo conferir o curso Introduction to Model Context Protocol (MCP) para ter uma experiência prática.
Normalmente, criar um fluxo entre apps exige integrar códigos frágeis. Com o MCP, você apenas entrega as ferramentas ao LLM. O agente pode ler uma conversa por e-mail, identificar um conflito de agenda verificando seu calendário e preparar um resumo no Google Docs — tudo sozinho.
Segurança e controles de administração do Workspace
Ao conceder acesso de modelos de IA a e-mails e arquivos corporativos, segurança de dados é o maior obstáculo para adoção de IA.
O servidor MCP do Workspace foi projetado desde o início para lidar com essa preocupação.
Ele trata a autenticação confiando integralmente no OAuth 2.0 e no IAM rigoroso do Google Cloud.
Não existem "chaves mestres" genéricas. O agente sempre atua em nome do usuário autenticado explicitamente, respeitando estritamente todas as permissões de compartilhamento do Google Workspace e as ACLs dos documentos.
Além disso, ele oferece controles robustos para administradores.
Os administradores do Workspace podem criar uma lista de permissões de ferramentas MCP específicas, monitorar o uso das APIs em toda a organização e aplicar regras de DLP (Prevenção de Perda de Dados) para garantir que os agentes não vazem acidentalmente documentos sensíveis do Drive ou e-mails para domínios externos não autorizados.
Configurando o acesso ao servidor MCP do Workspace
Antes de escrever código, "configuração" aqui significa ajustar as permissões no Google Cloud para acessar o servidor remoto.
Configurando o projeto no Google Cloud
Primeiro, você precisa habilitar tanto as APIs padrão do Workspace quanto os serviços MCP dedicados no seu projeto do Google Cloud.
- Acesse o Google Cloud Console.
- Habilite as APIs necessárias do Workspace: Gmail API, Google Drive API, Google Docs API e Google Calendar API.
- Habilite os serviços MCP: gmailmcp.googleapis.com, drivemcp.googleapis.com e calendarmcp.googleapis.com.
- Vá em APIs & Services > OAuth consent screen. Configure sua tela de consentimento para o público Internal. Em Data Access > Add or Remove Scopes, adicione manualmente os seguintes escopos para os servidores que pretende usar:
- Google Calendar: https://www.googleapis.com/auth/calendar.calendarlist.readonly, https://www.googleapis.com/auth/calendar.events.freebusy, https://www.googleapis.com/auth/calendar.events.readonly
- Google Chat: https://www.googleapis.com/auth/chat.spaces.readonly, https://www.googleapis.com/auth/chat.memberships.readonly, https://www.googleapis.com/auth/chat.messages.readonly, https://www.googleapis.com/auth/chat.users.readstate.readonly
- Google Drive: https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/drive.file
- Gmail: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.compose
- People API: https://www.googleapis.com/auth/directory.readonly, https://www.googleapis.com/auth/userinfo.profile, https://www.googleapis.com/auth/contacts.readonly
Gerando credenciais de usuário
Como os dados do Workspace são específicos por usuário, o endpoint remoto MCP exige um cabeçalho Authorization: Bearer <TOKEN> representando a pessoa usuária.
Acesse APIs & Services > Credentials e crie um OAuth 2.0 Client ID (tipo Desktop Application).
Baixe o arquivo JSON de credenciais. Ele será usado para obter o token de acesso OAuth 2.0 necessário por meio de um fluxo de login no navegador.
Clique em Create e copie o Client ID e o Client Secret. Você vai precisar deles no próximo passo.
Testando a conexão (Gemini CLI e Antigravity)
Antes de escrever qualquer código Python complexo para o agente, é altamente recomendado fazer um teste "Hello World" para verificar suas credenciais e garantir que os endpoints MCP remotos estão acessíveis.
Testar a conexão em um ambiente simplificado ajuda a isolar problemas de autenticação da lógica da sua aplicação.
Embora possamos testar a conexão tanto com o Gemini CLI quanto com a interface do Google Antigravity, vamos focar no Gemini CLI por enquanto.
Conectando via Gemini CLI
A forma mais rápida de testar a conectividade é usando o Gemini CLI.
Como o Workspace exige autenticação rígida, você configura o endpoint e suas credenciais OAuth no arquivo ~/.gemini/settings.json:
{
"mcpServers": {
"calendar": {
"httpUrl": "https://calendarmcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/calendar.calendarlist.readonly",
"https://www.googleapis.com/auth/calendar.events.freebusy",
"https://www.googleapis.com/auth/calendar.events.readonly"
]
}
},
"drive": {
"httpUrl": "https://drivemcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/drive.file"
]
}
},
"gmail": {
"httpUrl": "https://gmailmcp.googleapis.com/mcp/v1",
"oauth": {
"enabled": true,
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"scopes": [
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.compose"
]
}
}
}
}
Depois de atualizar o arquivo de configurações, você pode iniciar o Gemini CLI e executar o comando /mcp list.
Você verá os servidores do Workspace recém-configurados listados como "Ready", mas com a indicação "(OAuth not authenticated)".
Isso confirma que o CLI leu sua configuração com sucesso e reconheceu as ferramentas remotas.
Executando testes básicos do Workspace
Agora que os servidores foram reconhecidos, você precisa se autenticar antes de usá-los. Comece executando o comando de autenticação para o seu endpoint do Gmail:
/mcp auth gmailIsso iniciará um fluxo OAuth 2.0 via navegador.
O CLI tentará abrir automaticamente seu navegador padrão, pedindo para você fazer login com sua conta do Google Workspace e conceder as permissões solicitadas.
Se o navegador não abrir automaticamente, o CLI fornecerá uma URL segura para você copiar e colar manualmente. Assim que concluir o login, o CLI confirmará a autenticação com sucesso e recarregará as ferramentas para aquele servidor.
Com a autenticação concluída, você pode testar a conexão com um prompt em linguagem natural:
my email for any messages containing the word 'Invoice'.O CLI executará a ferramenta nos bastidores, buscará os dados na sua caixa de entrada e o agente formatará tudo em uma resposta útil:
Projeto demo: construindo um agente do Workspace com o Google ADK
Vamos criar um agente do Workspace que se conecta a cinco serviços (Calendar, Chat, Drive, Gmail, People) e trata a autenticação com segurança.
Gerando Application Default Credentials (auth.py)
Antes de o agente rodar, ele precisa de um token OAuth para enviar aos endpoints MCP.
O Gemini CLI faz isso automaticamente com /mcp auth, mas para uma aplicação em Python precisamos gerar nosso próprio token e salvá-lo como Application Default Credentials (ADC).
Crie um arquivo chamado auth.py na raiz do projeto. Garanta que o seu client_secret.json baixado esteja no mesmo diretório.
Este script usa a biblioteca oficial google-auth-oauthlib para gerar uma URL de autenticação, trocar o código por um refresh token e gravá-lo no caminho padrão ~/.config/gcloud/application_default_credentials.json, onde o ADK pode encontrá-lo.
import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow
CLIENT_SECRET_FILE = 'client_secret.json'
SCOPES = [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/chat.spaces.readonly",
"https://www.googleapis.com/auth/chat.messages",
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/directory.readonly",
"https://www.googleapis.com/auth/contacts.readonly"
]
# Initialize the flow
flow = InstalledAppFlow.from_client_secrets_file(
CLIENT_SECRET_FILE,
scopes=SCOPES,
redirect_uri='http://localhost:8085/'
)
# Generate Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')
print("Copy this link and paste it into your browser:\\n", auth_url)
redirected_url = input("\\nPaste the full localhost URL here: ").strip()
# Exchange code for tokens
parsed_url = urlparse(redirected_url)
code = parse_qs(parsed_url.query).get('code', [None])[0]
flow.fetch_token(code=code)
# Save ADC
adc_data = {
"client_id": flow.credentials.client_id,
"client_secret": flow.credentials.client_secret,
"refresh_token": flow.credentials.refresh_token,
"type": "authorized_user"
}
adc_path = os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
os.makedirs(os.path.dirname(adc_path), exist_ok=True)
with open(adc_path, "w") as f:
json.dump(adc_data, f, indent=2)
print(f"Success! ADC saved to: {adc_path}")Execute o script no terminal: python3 auth.py
Ao executar, você precisará concluir um fluxo de autenticação manual:
- O script imprimirá uma URL longa do Google OAuth começando com https://accounts.google.com/o/oauth2/auth?...
- Copie essa URL inteira do terminal e cole no seu navegador.
- Selecione sua conta do Google Workspace e clique em Allow para autorizar o aplicativo.
- Em seguida, seu navegador redirecionará para uma página localhost. Observação: é totalmente normal aparecer um erro "Site can't be reached" nessa página.
- Copie a URL completa da barra de endereços do navegador (ela começará com http://localhost:8085/?state=...&code=...).
- Cole essa URL completa de volta no prompt do terminal, onde diz Paste the full localhost URL here:, e pressione Enter.
O script trocará o código por um token OAuth, salvará em ~/.config/gcloud/application_default_credentials.json e gerará um arquivo .env no diretório workspace_agent com as configurações do seu projeto no Google Cloud.
Seu ambiente local agora está totalmente autenticado!
Construindo o agente (agent.py)
Agora, crie um arquivo chamado agent.py.
Como os dados do Workspace são altamente sensíveis, os servidores MCP exigem que o token de acesso que acabamos de gerar seja injetado no cabeçalho HTTP de cada requisição.
Também precisamos configurar o ambiente do ADK com segurança.
Vamos decompor o código:
1. Ambiente e cache de token (TokenRelay)
Primeiro, carregamos o Application Default Credentials (ADC) do usuário gerado no passo anterior.
Uma parte crítica de agentes corporativos é fazer cache de tokens de forma eficiente. Se atualizarmos o token a cada execução de ferramenta, podemos atingir limites de API ou disparar loops de atualização durante tentativas.
A classe TokenRelay mantém o token em memória e só o renova quando faltar menos de 5 minutos para expirar.
import os
import datetime
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# Enable graceful error handling so timeouts return as tool outputs
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"
# Inject User ADC path globally
_adc_path = os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
if not os.path.exists(_adc_path):
raise FileNotFoundError("Please run 'python3 auth.py' first to generate credentials.")
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = _adc_path
creds, _ = google.auth.default()
class TokenRelay:
"""Manages in-memory caching of Google OAuth access tokens."""
def __init__(self, credentials):
self._creds = credentials
self._cached_token = None
self._expiry = None
def get_token(self) -> str:
now = datetime.datetime.now()
if (self._cached_token is None or self._expiry is None
or now >= (self._expiry - datetime.timedelta(minutes=5))):
self._creds.refresh(Request())
self._cached_token = self._creds.token
self._expiry = now + datetime.timedelta(minutes=50)
return self._cached_token or ""
token_relay = TokenRelay(creds)
token_relay.get_token()
def auth_header_provider(tool_context=None) -> dict[str, str]:
return {"Authorization": f"Bearer {token_relay.get_token()}"}
2. Configurando os conjuntos de ferramentas MCP
Com o cache de tokens pronto, configuramos nossas 5 conexões MCP. Usamos StreamableHTTPConnectionParams para conectar a endpoints de Server-Sent Events (SSE).
O que torna o McpToolset tão poderoso é que ele interroga dinamicamente o endpoint remoto. Ele busca automaticamente as ferramentas disponíveis e os esquemas JSON. Você não precisa fixar nada no código!
# Initialize the 5 GWS MCP servers with dynamic runtime provider
calendar_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
chat_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
drive_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
people_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)3. Inicializando o agente
Por fim, instanciamos nosso LlmAgent. Usamos o modelo gemini-2.5-flash, injetamos dinamicamente a data atual no prompt de sistema para que o LLM entenda tempo relativo ("esta semana", "hoje") e passamos os 5 conjuntos de ferramentas.
current_date = datetime.datetime.now().strftime("%Y-%m-%d")
root_agent = LlmAgent(
model="gemini-2.5-flash",
name='gws_adk_agent',
instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, and Contacts.
If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)Executando com o ADK Web
Em vez de escrever um loop Python personalizado, podemos testar e executar esse agente imediatamente usando a interface nativa do ADK Web. No terminal, inicie o servidor web:
adk web Isso inicia um servidor local de desenvolvimento. No navegador, acesse http://localhost:8080.
Você verá seu agente carregado e pronto para uso.
Pela interface, você pode conversar com o agente e observar como ele alterna, sem atrito, entre Gmail, Calendar e Drive para atender aos seus pedidos!
Testando o agente no mundo real
Agora que o agente está rodando, experimente fazer perguntas complexas e multifuncionais que normalmente exigiriam abrir três abas diferentes.
Por exemplo:
Prompt 1: Confira minha agenda de amanhã e resuma os tópicos das reuniões. Há documentos relevantes no meu Drive para elas?
O que acontece nos bastidores:
- O agente entende que primeiro precisa dos dados da agenda, então executa a ferramenta list_events, calculando dinamicamente a data de amanhã com base no prompt de sistema.
- Ele analisa a resposta em JSON para encontrar os títulos das reuniões.
- Percebendo que precisa de documentos relacionados, extrai palavras-chave desses títulos e as passa, sem atrito, para uma segunda chamada de ferramenta: search_files.
- Por fim, sintetiza as saídas dos servidores MCP do Calendar e do Drive em um único briefing, claro e objetivo.
Em vez de escrever wrappers de API e lógica de integração, você só fez uma pergunta, e o LLM definiu toda a orquestração em múltiplas etapas.
Prompt 2: Encontre todos os e-mails enviados por [Insira o e-mail] nos últimos 7 dias.
O que acontece nos bastidores:
- O agente pega seu pedido em linguagem natural e o traduz automaticamente para a sintaxe exata de consulta exigida pela API do Gmail.
- Chama a ferramenta search_threads, passando a string de consulta gerada dinamicamente.
- Recupera as conversas recentes, extrai os metadados relevantes e apresenta assuntos e datas de forma organizada.
Outros prompts para testar
As possibilidades são enormes quando você conecta todos os dados corporativos a um mecanismo de raciocínio.
Experimente estes prompts no seu ambiente local:
- "Encontre o último e-mail que recebi do meu gerente. Ele me pediu para fazer algo?"
- "Encontre no meu Drive o slide deck de kickoff do projeto, leia o conteúdo e me diga quais são as metas de Q3."
- "Tenho algum conflito de agenda na próxima semana?"
E agora? Desbloqueando a automação corporativa
Combinando o Agent Development Kit do Google com os servidores MCP padronizados do Workspace, você acabou de criar um assistente de nível corporativo em menos de cem linhas de código.
Mas isso é só o começo.
Veja o que essa arquitetura possibilita para desenvolvedores e empresas:
- Sistemas multiagentes: em vez de um agente gigantesco, você pode usar o ADK para criar uma frota de subagentes especializados. Um agente gerencia especificamente sua agenda e resolve conflitos; outro monitora rigidamente a caixa de entrada compartilhada do time e categoriza as solicitações.
- Ferramentas corporativas personalizadas: como o MCP é um padrão, você não fica restrito ao Workspace. É fácil adicionar outras ferramentas MCP ao seu agente — como um servidor MCP para Postgres para consultar o banco de dados de vendas da empresa, ou um servidor MCP para Jira para criar tickets automaticamente a partir de mensagens do Chat.
- Workflows automatizados: você pode tirar esse agente da interface do ADK Web e implantá-lo sem interface. Imagine um CRON diário que acorda seu agente às 8h, analisa sua caixa de entrada e agenda e envia um briefing resumido via Google Chat.
Conclusão
O servidor MCP do Google Workspace elimina o "código cola" necessário para conectar IA a apps de produtividade corporativa. Ao oferecer um endpoint remoto seguro e totalmente gerenciado, capacita desenvolvedores a criar workflows agentizados profundamente integrados que respeitam permissões de usuário e padrões de segurança corporativa desde o início.
Lembrete de boas práticas: aplique sempre o princípio do menor privilégio.
Ao atribuir escopos de OAuth aos seus agentes de IA, nunca conceda acesso de escrita (por exemplo, https://www.googleapis.com/auth/drive.file) se o agente só precisa ler dados.
Pronto para construir?
Continue sua jornada de aprendizado com nossos cursos guiados na DataCamp:
