Construindo um Servidor MCP Remoto para o Google Workspace (Sheets, Docs and Presentation)

Abílio Azevedo

03 de abril de 2026

Construindo um Servidor MCP Remoto para Google Workspace: Do Zero à Produção

Quer conectar seu assistente de IA ao Google Sheets, Docs e Slides? Nosso servidor MCP dá ao Claude, Cursor e outros clientes de IA acesso completo ao seu Google Workspace — leia planilhas, crie documentos, edite apresentações e muito mais. Sem chaves de API, sem configuração local. Basta adicionar uma URL e começar a trabalhar.

Experimente agora em gwk-mcp.abilioazevedo.com.br — $5/mês por 24 ferramentas para Sheets, Docs e Slides.

O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA — como Claude, ChatGPT e outros — se conectem a ferramentas externas e fontes de dados através de uma interface unificada. Pense nele como uma porta USB-C para IA: um protocolo, muitas ferramentas.

Em vez de cada cliente de IA implementar integrações personalizadas para cada serviço, o MCP define uma linguagem comum. Um servidor expõe ferramentas (funções que a IA pode chamar), e qualquer cliente compatível com MCP pode descobri-las e usá-las automaticamente.

Isso significa que você pode construir um servidor MCP e ele funciona em qualquer lugar — Claude Code, Claude.ai, Cursor, VS Code e qualquer outro cliente que fale o protocolo.

Por que Google Workspace?

O Google Workspace — Sheets, Docs e Slides — está no centro de como equipes gerenciam dados, documentos e apresentações. Conectar essas ferramentas a assistentes de IA abre fluxos de trabalho poderosos:

Pedir ao Claude para "ler os dados de vendas do Q1 da minha planilha e resumir tendências"
Fazer uma IA adicionar linhas a uma planilha de acompanhamento como parte de um fluxo automatizado
Criar novos documentos, apresentações ou planilhas sem sair do terminal
Buscar e substituir texto em uma apresentação inteira em segundos
Ler e resumir o conteúdo de um Google Doc

O desafio? O Google Workspace requer autenticação OAuth, e a maioria dos servidores MCP roda localmente. Queríamos algo diferente: um servidor MCP remoto que qualquer pessoa pode usar apenas adicionando uma URL — sem chaves de API, sem configuração local, sem arquivos de configuração.

Visão Geral da Arquitetura

O servidor é construído com Next.js implantado na Vercel, usando Neon Postgres para armazenamento de sessões. O ponto-chave é um fluxo OAuth de duas camadas:

┌─────────────┐      MCP OAuth       ┌──────────────────┐     Google OAuth     ┌─────────────┐
│  Cliente MCP │ ◄──────────────────► │  Servidor MCP    │ ◄─────────────────► │  APIs Google │
│  (Claude,    │   Bearer tokens,     │  (Next.js na     │   Tokens de acesso/ │  (Sheets,    │
│   Cursor)    │   PKCE, registro     │   Vercel)        │   refresh, tela de  │   Docs,      │
│              │   dinâmico de client │                  │   consentimento     │   Slides,    │
│              │                      │                  │                     │   Drive)     │
└─────────────┘                       └──────────────────┘                     └─────────────┘
                                             │
                                             ▼
                                      ┌──────────────┐
                                      │ Neon Postgres │
                                      │ (sessões,     │
                                      │  códigos auth,│
                                      │  clientes)    │
                                      └──────────────┘

Camada 1: MCP OAuth (Cliente ↔ Servidor)

Quando um cliente MCP se conecta, ele descobre os requisitos de autenticação via endpoints well-known padrão:

/.well-known/oauth-protected-resource — informa ao cliente que este recurso é protegido por OAuth
/.well-known/oauth-authorization-server — fornece os metadados do servidor de autorização (endpoints, fluxos suportados)
/oauth/register — registro dinâmico de cliente (o cliente se registra automaticamente)

Isso segue a especificação MCP, então qualquer cliente compatível lida com isso de forma transparente. PKCE é suportado para segurança.

Camada 2: Google OAuth (Servidor ↔ Google)

Quando o usuário precisa se autenticar:

/oauth/authorize recebe a solicitação de autenticação do cliente MCP e redireciona para a tela de consentimento do Google
O usuário concede acesso ao Google Sheets, Docs, Slides e Drive
/oauth/callback recebe os tokens do Google, armazena-os no Postgres e redireciona de volta ao cliente MCP com um código de autorização
/oauth/token troca o código por um token de acesso de sessão

O resultado final: o cliente MCP recebe um Bearer token, e o servidor mantém as credenciais do Google de forma segura.

O Endpoint MCP

O núcleo do servidor é um único Route Handler do Next.js em POST /mcp. Cada requisição cria uma nova instância de McpServer com um WebStandardStreamableHTTPServerTransport:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";

export async function POST(request: NextRequest) {
  const token = request.headers.get("authorization")?.replace("Bearer ", "");
  if (!token) return unauthorizedResponse();

  const server = new McpServer({
    name: "google-workspace",
    version: "0.2.0",
  });

  registerTools(server, () => resolveGoogleAuth(token));

  const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  await server.connect(transport);

  return await transport.handleRequest(request);
}

O WebStandardStreamableHTTPServerTransport é a peça-chave — ele funciona com as APIs Web Standard Request/Response que os Route Handlers do Next.js utilizam, tornando a implantação em plataformas serverless como a Vercel algo simples.

Ferramentas Expostas

O servidor registra 24 ferramentas em três produtos do Google Workspace:

Google Sheets (8 ferramentas)

Ferramenta	Descrição
`list_spreadsheets`	Pesquisa e lista planilhas do Google Drive
`get_spreadsheet`	Obtém metadados da planilha (nomes das abas, dimensões)
`read_sheet`	Lê dados de um intervalo (retorna tabela formatada)
`write_sheet`	Escreve dados em um intervalo específico (sobrescreve)
`append_rows`	Adiciona linhas ao final de uma aba
`update_cells`	Atualiza células individuais em posições específicas
`create_spreadsheet`	Cria uma nova planilha
`batch_get`	Lê múltiplos intervalos em uma única requisição

Google Docs (7 ferramentas)

Ferramenta	Descrição
`list_documents`	Pesquisa e lista Google Docs do Drive
`get_document`	Obtém metadados e estrutura do documento
`read_document`	Lê o conteúdo de texto completo de um documento
`create_document`	Cria um novo Google Doc
`append_text_to_document`	Adiciona texto ao final de um documento
`insert_text_in_document`	Insere texto em uma posição específica
`replace_text_in_document`	Busca e substitui texto em um documento

Google Slides (9 ferramentas)

Ferramenta	Descrição
`list_presentations`	Pesquisa e lista apresentações do Drive
`get_presentation`	Obtém metadados da apresentação (número de slides, IDs)
`read_slide`	Lê texto e elementos de um slide específico
`read_all_slides`	Lê texto de todos os slides de uma apresentação
`create_presentation`	Cria uma nova apresentação
`add_slide`	Adiciona um novo slide com layout predefinido
`add_text_to_slide`	Insere texto em uma forma/caixa de texto de um slide
`replace_text_in_presentation`	Busca e substitui texto em todos os slides
`delete_slide`	Remove um slide de uma apresentação

Cada ferramenta usa schemas Zod para validação de entrada e inclui descrições que ajudam os clientes de IA a entender quando e como usá-las:

server.registerTool(
  "read_sheet",
  {
    description: "Read data from a spreadsheet range. Returns a formatted table.",
    inputSchema: {
      spreadsheet_id: z.string().describe("The spreadsheet ID"),
      range: z.string().describe("A1 notation range, e.g. 'Sheet1!A1:D10'"),
    },
  },
  async ({ spreadsheet_id, range }) => {
    const auth = await getAuth();
    const data = await sheetsLib.readSheet(auth, spreadsheet_id, range);
    // Formata como tabela legível...
    return { content: [{ type: "text", text }] };
  }
);

O servidor também inclui um prompt (google_workspace_guide) que fornece orientações de boas práticas para assistentes de IA usarem as ferramentas de forma eficiente — como preferir intervalos estreitos, usar batch_get para múltiplas leituras e explorar a estrutura antes de ler o conteúdo completo.

Stack Tecnológica

Next.js 15 — App Router com Route Handlers para todos os endpoints
Vercel — Implantação serverless com deploy via git push
Neon Postgres — PostgreSQL serverless para armazenamento de sessões/tokens
Prisma — ORM com três tabelas: oauth_clients, auth_codes, sessions
@modelcontextprotocol/sdk — SDK oficial do MCP para TypeScript
googleapis — Cliente oficial do Google para Node.js para as APIs Sheets, Docs, Slides e Drive
Zod — Validação de schemas para entradas das ferramentas

Implantação

O projeto é implantado automaticamente a cada push para master. O comando de build cuida de tudo:

prisma generate && prisma migrate deploy && next build

As migrações do Prisma rodam automaticamente durante o build, então mudanças no schema do banco de dados são implantadas junto com as mudanças de código de forma transparente.

Como Usar

Adicionando ao Claude Code

Adicione a URL do servidor à configuração do seu cliente MCP:

{
  "mcpServers": {
    "google-workspace": {
      "url": "https://gwk-mcp.abilioazevedo.com.br/mcp"
    }
  }
}

É só isso. Na primeira vez que você usar uma ferramenta, o fluxo OAuth é iniciado — seu navegador abre, você concede acesso ao Google Workspace e está conectado.

Adicionando ao Claude.ai

Vá em Configurações > Servidores MCP > Adicionar Servidor e cole a URL:

https://gwk-mcp.abilioazevedo.com.br/mcp

O Claude lidará com o fluxo de autenticação automaticamente.

Inspecionando e Depurando com o MCP Inspector

O MCP Inspector é uma ferramenta essencial para desenvolver e depurar servidores MCP. Ele fornece uma interface web onde você pode ver as capacidades do servidor, testar ferramentas interativamente e inspecionar as mensagens do protocolo.

Executando o Inspector

Para inspecionar nosso servidor MCP remoto, execute:

npx @modelcontextprotocol/inspector https://gwk-mcp.abilioazevedo.com.br/mcp

Isso inicia uma interface web local (geralmente em http://localhost:6274) que se conecta ao servidor remoto.

O que Você Pode Fazer com o Inspector

Autenticar — O Inspector suporta o fluxo completo de OAuth do MCP. Clique em "Connect" e ele guiará você pela autenticação do Google, assim como um cliente MCP real faria.
Listar Ferramentas — Veja todas as 24 ferramentas que o servidor expõe, junto com suas descrições e schemas de entrada. Ótimo para verificar se suas definições de ferramentas estão corretas.
Chamar Ferramentas — Preencha parâmetros e execute ferramentas diretamente. Por exemplo, você pode chamar list_spreadsheets para ver suas planilhas do Google, depois chamar read_sheet com um ID de planilha e intervalo específicos.
Inspecionar Mensagens do Protocolo — Veja as mensagens JSON-RPC brutas trocadas entre cliente e servidor. Isso é invaluável para depurar problemas com chamadas de ferramentas, autenticação ou transporte.
Testar Tratamento de Erros — Tente chamar ferramentas com parâmetros inválidos para verificar se suas respostas de erro fazem sentido.

Exemplo de Fluxo de Trabalho com o Inspector

1. Execute: npx @modelcontextprotocol/inspector https://gwk-mcp.abilioazevedo.com.br/mcp
2. Abra http://localhost:6274 no seu navegador
3. Clique em "Connect" → Complete o OAuth do Google no popup
4. Navegue até a aba "Tools" → Veja todas as 24 ferramentas registradas
5. Selecione "list_spreadsheets" → Clique em "Run" → Veja suas planilhas
6. Selecione "read_document" → Insira um document_id → Veja o conteúdo do documento
7. Selecione "get_presentation" → Insira um presentation_id → Veja a estrutura dos slides

O Inspector também é útil para desenvolvimento local:

# Inicie o servidor de desenvolvimento
pnpm dev

# Em outro terminal, aponte o inspector para o localhost
npx @modelcontextprotocol/inspector http://localhost:3100/mcp

Lições Aprendidas

1. Normalização do Header Accept

Alguns clientes MCP enviam Accept: */* em vez dos tipos de conteúdo específicos que o SDK espera (application/json, text/event-stream). Tivemos que normalizar o header nas requisições de entrada para evitar que o transporte rejeitasse requisições válidas.

2. Não Feche o Servidor Cedo Demais

O WebStandardStreamableHTTPServerTransport retorna um stream SSE (Server-Sent Events). O corpo da resposta é populado de forma assíncrona — se você chamar server.close() imediatamente após obter a resposta, ele mata o stream antes do cliente lê-lo. Deixe o ciclo de vida natural da função serverless cuidar da limpeza.

3. CORS Importa para Servidores Remotos

Diferente de servidores MCP locais, um servidor remoto precisa de headers CORS adequados. Clientes MCP rodando em navegadores (como o Claude.ai) precisam fazer requisições cross-origin para o seu servidor. Todo endpoint — incluindo preflight OPTIONS — precisa dos headers corretos.

4. Refresh de Token é Crítico

Tokens de acesso do Google expiram após ~1 hora. O servidor verifica a expiração do token em cada requisição e faz o refresh de forma transparente usando o refresh token armazenado. Sem isso, os usuários precisariam se reautenticar constantemente.

5. Escalando para Múltiplas APIs do Google

Começar com Sheets e depois expandir para Docs e Slides nos ensinou o valor de manter uma separação limpa entre a camada de registro de ferramentas MCP e os wrappers das APIs do Google. Cada serviço Google (sheets.ts, docs.ts, slides.ts) exporta funções puras que recebem um GoogleOAuth2Client e retornam dados estruturados. O route handler do MCP apenas orquestra — registra ferramentas, resolve autenticação, formata saída. Adicionar um novo serviço Google é simples: escreva o wrapper da API, registre as ferramentas.

Conclusão

Construir um servidor MCP remoto é uma forma poderosa de dar aos assistentes de IA acesso a serviços externos. O protocolo MCP lida com a complexidade da descoberta de ferramentas e autenticação, enquanto plataformas como Vercel e Neon tornam a implantação e o armazenamento de dados algo simples.

A principal vantagem de um servidor remoto sobre um local é zero configuração para os usuários finais — eles adicionam uma URL e se autenticam uma vez. Sem chaves de API para gerenciar, sem processos locais para rodar, sem arquivos de configuração para manter.

Ao expandir do Google Sheets para a suíte completa do Google Workspace — Sheets, Docs e Slides — um único servidor MCP se torna uma ponte abrangente de produtividade entre a IA e as ferramentas que as equipes usam todos os dias.

Abílio Azevedo.