Configurar o servidor MCP do Google Docs

O Documentos oferece um servidor remoto do Protocolo de Contexto de Modelo (MCP) que permite que agentes de IA interajam com segurança com os dados do Documentos. Ao configurar o servidor MCP do Documentos, você permite que aplicativos de IA, como o Google Antigravity e o Claude, realizem ações no Documentos.

O servidor MCP do Documentos oferece uma maneira padronizada para que os agentes de IA:

  • Ler dados: ler informações estruturais e conteúdo de texto do documento.
  • Entre em ação: atualize o estilo e a estrutura do documento usando atualizações em lote.
  • Respeitar a segurança: herdar as mesmas permissões e controles de governança de dados do usuário.

Pré-requisitos

Configurar o servidor MCP do Documentos

Para usar o servidor MCP do Documentos, ative-o no projeto do Google Cloud e configure o aplicativo de IA para se conectar a ele.

Ative as APIs

Para usar o servidor MCP do Documentos, ative a seguinte API no seu projeto do Google Cloud:

  • API Google Docs

CLI

gcloud services enable docs.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

Ative as APIs no console do Google Cloud:

Ativar as APIs

Ativar os serviços do MCP

Para ativar os componentes do MCP para o app Documentos, ative o seguinte serviço no seu projeto na nuvem do Google Cloud:

  • API MCP do Google Docs

CLI

gcloud services enable docsmcp.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Console

Ative os serviços do MCP no console do Google Cloud:

Ativar os serviços do MCP

O servidor MCP do Documentos usa o OAuth 2.0 para autenticação e autorização. É necessário configurar a tela de permissão OAuth antes de criar um ID do cliente OAuth.

  1. No console do Google Cloud, acesse Plataforma de autenticação do Google > Branding.

    Acessar Branding

  2. Se você já configurou a Plataforma de autenticação do Google, pode definir as seguintes configurações da tela de permissão OAuth em Branding, Público e Acesso a dados. Se aparecer a mensagem A plataforma Google Auth ainda não está configurada, clique em Começar:

    1. Em Informações do app, em Nome do app, digite Docs MCP Server.
    2. Em E-mail para suporte do usuário, selecione seu endereço de e-mail ou um Grupo do Google adequado.
    3. Clique em Próxima.
    4. Em Público-alvo, selecione Interno. Se não for possível selecionar Interno, selecione Externo.
    5. Clique em Próxima.
    6. Em Dados de contato, insira um endereço de e-mail para receber notificações sobre mudanças no projeto.
    7. Clique em Próxima.
    8. Em Concluir, leia a Política de Dados do Usuário dos Serviços de API do Google e, se concordar, selecione Concordo com a Política de Dados do Usuário dos Serviços de API do Google.
    9. Clique em Continuar.
    10. Clique em Criar.
    11. Se você selecionou Externo como tipo de usuário, adicione usuários de teste:
      1. Clique em Público-alvo.
      2. Em Usuários de teste, clique em Adicionar usuários.
      3. Insira seu endereço de e-mail e os outros usuários de teste autorizados. Depois, clique em Salvar.
  3. Clique em Acesso a dados > Adicionar ou remover escopos. Um painel vai aparecer com uma lista de escopos para cada API que você ativou no projeto na nuvem do Google Cloud.

    1. Em Adicionar escopos manualmente, cole os escopos do servidor MCP do Documentos:

      • https://www.googleapis.com/auth/drive.readonly
      • https://www.googleapis.com/auth/drive.file
      • https://www.googleapis.com/auth/documents.readonly
      • https://www.googleapis.com/auth/documents
    2. Clique em Adicionar à tabela.

    3. Clique em Atualizar.

    4. Depois de selecionar os escopos necessários para o app, na página Acesso a dados, clique em Salvar.

Configurar o aplicativo de IA

Para adicionar o servidor MCP remoto do Documentos ao seu aplicativo de IA, siga as instruções do aplicativo.

Os IDs do cliente OAuth 2.0 delegados pelo usuário que chamam o servidor MCP do Documentos precisam ter a opção Usar este cliente para um agente com tecnologia de IA selecionada em Plataforma de autenticação do Google > Clientes. Para atualizar um ID do cliente OAuth 2.0, selecione essa configuração em Plataforma de autenticação do Google > Clientes, conforme descrito em Gerenciar clientes OAuth. Se não for possível mudar essa configuração em um cliente atual ou se o cliente também oferecer suporte a recursos que não são de agente, crie um novo ID do cliente OAuth 2.0 para seu agente de IA. Para solicitações rejeitadas, contas de serviço com delegação em todo o domínio ou Google Apps Script, consulte Solução de problemas.

Antigravity

Para adicionar o servidor MCP remoto do Google Docs ao Antigravity, adicione a configuração do servidor ao arquivo mcp_config.json. Estas instruções são válidas para o Antigravity 2.0, o IDE do Antigravity e a CLI do Antigravity.

  1. Crie um ID do cliente OAuth 2.0 e uma chave secreta:

    1. No console do Google Cloud, acesse Plataforma de autenticação do Google > Clientes > Criar cliente.

      Acesse "Criar cliente"

    2. Selecione Aplicativo da Web como o tipo de aplicativo.

    3. Digite um Nome.

    4. Na seção URIs de redirecionamento autorizados, clique em + Adicionar URI e adicione https://antigravity.google/oauth-callback no campo URIs.

    5. Selecione Usar este cliente para um agente com tecnologia de IA.

    6. Clique em Criar e copie o ID do cliente e a chave secreta do cliente.

  2. Abra ou crie o arquivo de configuração ~/.gemini/config/mcp_config.json.

  3. Adicione a configuração mcpServers a mcp_config.json:

    {
      "mcpServers": {
        "docs": {
          "serverUrl": "https://docsmcp.googleapis.com/mcp/v1",
          "oauth": {
            "clientId": "OAUTH_CLIENT_ID",
            "clientSecret": "OAUTH_CLIENT_SECRET"
          }
        }
      }
    }
    

    Substitua:

    • OAUTH_CLIENT_ID: o ID do cliente que você criou.
    • OAUTH_CLIENT_SECRET: a chave secreta do cliente que você criou.
  4. Economize mcp_config.json.

  5. Autentique o servidor MCP. É possível autenticar usando as configurações da GUI ou da CLI:

    • Para o IDE do Antigravity ou a GUI (Antigravity 2.0):

      1. Abra a tela de configurações (por exemplo, clique em Configurações no canto inferior esquerdo ou abra Configurações do usuário do Antigravity).
      2. Acesse Personalizações.
      3. Em Servidores MCP instalados, clique em Atualizar.
      4. Encontre docs na lista, clique em Autenticar, faça login na sua Conta do Google, copie o código de autorização, cole-o na caixa de diálogo de entrada e clique em Enviar.
    • Para a CLI do Antigravity:

      1. Inicie a CLI do Antigravity:

        agy
        
      2. Abra o painel de gerenciamento interativo do MCP executando:

        /mcp
        
      3. Use as teclas de seta para selecionar docs, vá para a ação Autenticar e pressione Enter. Conclua o processo de login no navegador, copie o código de autorização, cole-o no prompt do terminal e pressione Enter.

  6. Verifique se o servidor está configurado corretamente e em execução:

    • Para o IDE do Antigravity ou a GUI: um botão Sair é exibido ao lado do servidor em Personalizações > Servidores MCP instalados.
    • Para a CLI do Antigravity: abra o painel /mcp para conferir os servidores MCP configurados. Os servidores verificados e autenticados mostram Autenticado ao lado dos nomes no painel interativo da TUI. Selecione qualquer servidor na visualização do painel para inspecionar o status dele e listar todas as ferramentas disponíveis.

O servidor MCP remoto está pronto para uso no Antigravity.

Claude

Para usar o servidor MCP remoto do Documentos com o Claude.ai ou o Claude Desktop, você precisa ter o plano Claude Enterprise, Pro, Max ou Team.

Para adicionar o servidor MCP remoto do Docs ao Claude, configure um conector personalizado com um ID do cliente e uma chave secreta do cliente OAuth.

  1. Crie um ID do cliente OAuth 2.0 e uma chave secreta:

    1. No console do Google Cloud, acesse Plataforma de autenticação do Google > Clientes > Criar cliente.

      Acesse "Criar cliente"

    2. Selecione Aplicativo da Web como o tipo de aplicativo.

    3. Digite um Nome.

    4. Na seção URIs de redirecionamento autorizados, clique em + Adicionar URI e adicione https://claude.ai/api/mcp/auth_callback no campo URIs.

    5. Selecione Usar este cliente para um agente com tecnologia de IA.

    6. Clique em Criar e copie o ID do cliente e a chave secreta do cliente.

  2. Configure o servidor MCP no Claude:

    1. No Claude.ai ou no Claude Desktop, acesse Configurações > Conectores ou Configurações de administrador > Conectores.
    2. Clique em Adicionar conector personalizado.
    3. Insira os detalhes de conexão do produto Documentos:
      • Nome do servidor: Docs.
      • URL do servidor MCP remoto: https://docsmcp.googleapis.com/mcp/v1
    4. Em Configurações avançadas, insira o ID do cliente OAuth e a chave secreta do cliente OAuth.
    5. Clique em Adicionar.

Outros

Muitos aplicativos de IA têm maneiras de se conectar a um servidor MCP remoto. Normalmente, é necessário inserir detalhes sobre o servidor, como nome, endpoints, protocolo de transporte e método de autenticação. Para o servidor MCP remoto do Documentos, insira o seguinte:

  • Nome do servidor: docs

  • URL do servidor: https://docsmcp.googleapis.com/mcp/v1

  • Transporte: HTTP com streaming

  • Autenticação: o servidor MCP remoto do Documentos usa o OAuth 2.0. Ao criar o cliente OAuth 2.0, selecione Usar este cliente para um agente com tecnologia de IA. Para mais detalhes, consulte Aprenda Mais sobre autenticação e autorização.

    Para evitar solicitações de login de hora em hora com um cliente OAuth de aplicativo da Web, configure seu cliente do MCP para solicitar acesso off-line usando access_type=offline ou o escopo offline_access. Veja mais detalhes em Solicitações de login repetidas a cada hora.

Para mais detalhes sobre como conectar diferentes tipos de aplicativos de IA, consulte Configurar o MCP em um aplicativo de IA.

Testar o servidor MCP do Documentos

Depois de configurar o aplicativo de IA, verifique a conexão executando alguns comandos de teste.

Faça as seguintes perguntas ao seu aplicativo de IA:

  • "Mostre o conteúdo estrutural do documento do Google abcd123."

    O cliente busca a estrutura e o conteúdo do documento usando docs.read_doc.

  • "Insira o título 'Meu plano de marketing' no documento do Google abcd123."

    O cliente executa docs.update_doc para atualizar elementos estruturais e inserir texto.

Se as ferramentas forem executadas com sucesso e você receber respostas relevantes, seu servidor MCP do Documentos está configurado corretamente.

Solução de problemas

Use as seções a seguir para resolver problemas comuns de autenticação e conexão com o servidor MCP do Documentos.

Verificar eventos de registro do OAuth

Se você tiver problemas para se conectar ao servidor MCP, verifique se há erros nos registros do OAuth. Peça para o admin do Google Workspace analisar os eventos de registro do OAuth na ferramenta de investigação de segurança.

Solicitações recusadas de clientes OAuth delegados pelo usuário

Se as solicitações para o servidor MCP forem rejeitadas, verifique se o ID do cliente OAuth 2.0 delegado pelo usuário para o fluxo OAuth de três etapas tem a opção Usar este cliente para um agente com tecnologia de IA selecionada em Plataforma de autenticação do Google > Clientes:

  • O cliente atual é compatível com a configuração: selecione Usar este cliente para um agente com tecnologia de IA no cliente OAuth atual.
  • Não é possível atualizar o cliente atual: crie um novo cliente OAuth com a opção Usar este cliente para um agente com tecnologia de IA selecionada e atualize seu app para usá-lo.
  • O cliente atual também oferece suporte a recursos que não são de agentes: crie um cliente OAuth separado para o agente de IA e mantenha o cliente atual para os recursos que não são de agentes.

Para instruções, consulte Configurar seu aplicativo de IA e Gerenciar clientes OAuth.

Contas de serviço com delegação em todo o domínio

Se o app usa uma conta de serviço com delegação em todo o domínio para OAuth de duas etapas, não é possível selecionar Usar este cliente para um agente com tecnologia de IA porque as contas de serviço não são gerenciadas na Plataforma de autenticação do Google > Clientes:

  • Controle de acesso: as solicitações ao servidor MCP dessas contas de serviço não são rejeitadas por falta da configuração do agente. Em vez disso, o acesso é regido pelas configurações de delegação em todo o domínio que o administrador do Google Workspace gerencia. Para mais detalhes sobre as configurações de administrador, consulte Controlar o acesso da API com a delegação em todo o domínio.
  • Ações sensíveis: os servidores MCP do Google Workspace ainda retornam comandos de preenchimento de formulário para confirmação com human-in-the-loop em chamadas de ferramentas sensíveis feitas por falsificação de identidade do usuário com delegação em todo o domínio.

Solicitações do Apps Script

Se você chamar o servidor MCP pelo Apps Script, não será possível selecionar Usar este cliente para um agente com tecnologia de IA no cliente OAuth padrão que o Apps Script cria e gerencia para seu script. Isso se aplica mesmo que o script use um projeto padrão do Google Cloud.

Para chamar o servidor MCP do Apps Script, faça o seguinte:

  1. No console do Google Cloud, acesse Plataforma de autenticação do Google > Clientes, crie um cliente OAuth e selecione Usar este cliente para um agente com tecnologia de IA.
  2. No script, use a biblioteca OAuth2 para o Apps Script para autorizar usuários com esse cliente OAuth.
  3. Ao chamar o servidor MCP, envie o token de acesso retornado pela biblioteca, em vez do token de ScriptApp.getOAuthToken.

Os projetos do Apps Script que não chamam servidores MCP do Google Workspace não são afetados.

Solicitações de login repetidas a cada hora

Se você precisar fazer login novamente a cada hora, seu cliente do MCP não está recebendo ou usando um token de atualização. Isso geralmente acontece nas seguintes situações:

  • Acesso off-line ausente em um cliente OAuth de aplicativo da Web: ao contrário dos clientes OAuth de app para computador, os clientes OAuth de aplicativo da Web usam o acesso on-line por padrão. Para solicitar um token de atualização, inclua access_type=offline ou o escopo offline_access do OpenID Connect (OIDC) com pelo menos um escopo de API e não defina access_type=online.
  • Reautorizar um app que já recebeu consentimento: o servidor OAuth 2.0 do Google emite um token de atualização na primeira vez que um usuário concede acesso off-line. Se um usuário já tiver autorizado seu cliente OAuth sem acesso off-line ou se o cliente do MCP tiver perdido o token de atualização armazenado, os logins seguintes podem não retornar um novo token de atualização. Inclua prompt=consent na solicitação de autorização ou remova o acesso do app em Conexões da Conta do Google e faça login novamente.
  • Token do portador estático: se você transmitir um token de acesso bruto em um cabeçalho Authorization, como a saída de gcloud auth print-access-token, o token vai expirar após uma hora, a menos que o cliente o atualize.

Para mais detalhes, consulte Atualizar um token de acesso.

Referência de ferramentas

As ferramentas a seguir estão disponíveis para o servidor MCP do Documentos. Para esquemas de entrada e saída, consulte a referência do MCP do Documentos:

Consideração importante sobre segurança: injeção indireta de comando

Quando você expõe um modelo de linguagem a dados não confiáveis, há o risco de um ataque de injeção indireta de comando. Como os aplicativos de IA, como o Google Antigravity, têm acesso a ferramentas e APIs avançadas pelo servidor MCP do Documentos, eles podem ler, modificar e excluir dados na sua Conta do Google.

Para mitigar esses riscos, é preciso filtrar comandos e respostas em busca de conteúdo mal-intencionado ou ataques de injeção de comando. É possível usar o Model Armor fornecido pelo Google ou sua própria solução, desde que você a documente para que os usuários possam aceitar esse risco. Para instruções, consulte Configurar a segurança dos servidores MCP do Google Workspace.

Siga estas práticas recomendadas:

  • Use apenas ferramentas confiáveis. Nunca conecte o servidor MCP do Documentos a aplicativos não confiáveis ou não verificados.
  • Tenha cuidado com entradas não confiáveis. Evite pedir que o aplicativo de IA processe documentos ou outros recursos de fontes não verificadas. Essas entradas podem conter instruções ocultas que podem sequestrar sua sessão e permitir que um invasor modifique, roube ou exclua seus dados.
  • Revise todas as ações. Sempre revise com cuidado as ações realizadas pelo aplicativo de IA em seu nome para garantir que elas sejam precisas e correspondam às suas intenções.