StudyPulse: Construindo um Planejador de Estudos para Estudantes com MCP e Google Cloud

Eu construí um planejador de estudos que rastreia a conclusão do syllabus, envia relatórios de progresso através do Gmail e adiciona exames ao Google Calendar sem expor tokens do Google ao aplicativo web.

O Problema

A maioria dos aplicativos de estudo rastreia atividade — "você estudou por 3 horas." Eles não dizem se você está pronto para um exame. Um estudante pode passar semanas em um aplicativo e ainda não saber se realmente terminou o syllabus.

Eu estava ajudando uma amiga a estudar para um exame competitivo. Ela tinha aplicativos para anotações, para perguntas, para horários. Nenhum deles respondia: "De tudo que eu preciso saber, quanto eu realmente sei agora?"

A Solução: Um Número, Uma Lista

StudyPulse é um aplicativo web que faz uma coisa bem: ele mostra qual fração do seu syllabus está concluída e o que você deve estudar a seguir. Você adiciona disciplinas, as divide em tópicos, e as marca. O aplicativo calcula o progresso real — levando em conta o trabalho parcial — e permite que você envie um relatório para um pai ou mentor a partir do seu próprio Gmail.

A Arquitetura: Por que o MCP é Importante

A principal decisão arquitetônica foi manter os tokens do Google OAuth fora da aplicação web. Em vez de permitir que o aplicativo web se comunique diretamente com o Gmail e o Google Calendar, todas as operações relacionadas ao Google passam por um servidor MCP separado.

Aqui é onde fica interessante. O aplicativo poderia chamar o Gmail e o Google Calendar diretamente. Em vez disso, ele não faz isso. O Gmail e o Calendar se comunicam com um servidor do Protocolo de Contexto do Modelo — um serviço autônomo que possui os tokens do Google e expõe ferramentas.

Aplicativo Web StudyPulse
        |
        | HTTPS + segredo compartilhado
        v
Servidor MCP StudyPulse
        |
        | Tokens do Google OAuth
        v
API do Gmail + API do Google Calendar

O aplicativo web → (HTTPS + segredo compartilhado) → servidor MCP → (tokens do Google OAuth) → Gmail + Calendar

Por quê? Três razões:

1. Isolamento de tokens: O aplicativo web nunca vê um token do Google. Nenhum token vaza de uma vulnerabilidade do aplicativo web.
2. Ferramentas reutilizáveis: As mesmas nove ferramentas do MCP funcionam a partir da web, de um trabalho cron ou do Claude Desktop. Uma integração, muitos clientes.
3. Clara separação de preocupações: A infraestrutura do Google é problema de outra pessoa. O aplicativo web é apenas lógica de negócios.

Como Configuramos: Google Cloud Console

O Google Cloud Console é usado para configurar o Gmail, o Google Calendar, permissões OAuth, usuários de teste e credenciais de aplicativo.

A parte do Google é direta:

1. Criar um projeto no Google Cloud Console
2. Ativar duas APIs: API do Gmail, API do Google Calendar (ambas gratuitas)
3. Tela de consentimento OAuth: marcá-la como Externa, adicionar seus usuários de teste
4. Adicionar quatro escopos à tela de consentimento: gmail.send, gmail.compose, calendar.events, userinfo.email
5. Criar um cliente OAuth (tipo aplicativo web), adicionar seu URI de redirecionamento: http://localhost:3000/api/google/oauth/callback

O aplicativo lida com o fluxo OAuth a partir daí. Os estudantes fazem login com um link mágico para o StudyPulse, e depois clicam em "Conectar Google" nas Configurações. Eles consentem uma vez — tokens de atualização permitem que eles permaneçam conectados.

A Pilha Tecnológica

• Web: Next.js 15, React 19, Supabase (auth + banco de dados)
• Servidor MCP: Node.js + @modelcontextprotocol/sdk
• APIs: Gmail, Google Calendar, Google OAuth
• Hospedagem: Vercel (web), qualquer host Node (servidor MCP)
• Banco de dados: PostgreSQL com segurança em nível de linha

server.registerTool(
  'calendar_create_event',
  { description: 'Criar um evento de exame para o estudante' },
  async (args) => ok(await createEvent(await clientForUser(args.userId), args)),
);

O Que Nos Surpreendeu

O projeto nos ensinou que a complexidade da integração muitas vezes é menos sobre escrever chamadas de API e mais sobre lidar com autenticação, segurança e propriedade de dados corretamente.

1. Testes de OAuth são complicados: Conectar/desconectar manualmente contas do Google para cada teste. Em produção, os tokens de atualização do modo de teste expiram a cada 7 dias, então os estudantes têm que se reconectar semanalmente. Isso é por design para segurança, mas é um ponto de atrito.

2. MCP foi a escolha certa: Isolar tokens nos forçou a pensar claramente sobre o limite da API. O conjunto de ferramentas resultante (study_progress_snapshot, gmail_send_report, calendar_create_event) funciona fora do aplicativo web também — clientes do Claude Desktop podem usar o sa