Configurar o servidor MCP da API People

A API People oferece um servidor Protocolo de Contexto de Modelo (MCP) remoto que permite que agentes de IA interajam com segurança com dados de perfil e de contato do Google Workspace. Ao configurar o servidor MCP da API People, você permite que aplicativos de IA como a CLI do Gemini, o Claude ou IDEs realizem ações usando a API People.

O servidor MCP da API People oferece uma maneira padronizada para que os agentes de IA possam:

  • Ler dados: recuperar perfis de usuários e pesquisar contatos ou pessoas do diretório.
  • 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 da API People

Para usar o servidor MCP da API People, ative-o no seu projeto do Google Cloud e configure o cliente MCP para se conectar a ele.

Ativar a API e o serviço MCP

Para usar o servidor MCP da API People, ative o seguinte serviço no seu projeto do Google Cloud:

  • API People

CLI

gcloud services enable people.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

O servidor MCP da API People 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 Google Auth Platform > Branding.

    Acessar a página "Branding"

  2. Se você já tiver configurado a plataforma de autenticação do Google, poderá configurar as seguintes opções da tela de permissão OAuth em Branding, Público-alvo e Acesso a dados. Se você encontrar a mensagem A plataforma de autenticação do Google ainda não está configurada, clique em Começar:

    1. Em Informações do app, em Nome do app, digite People API 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, escolha Externo.
    5. Clique em Próxima.
    6. Em Informações de contato, insira um Endereço de e-mail em que você possa receber notificações sobre mudanças no seu 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 o 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 aparece com uma lista de escopos para cada API ativada no projeto do Google Cloud.

    1. Em Adicionar escopos manualmente, cole os escopos do servidor MCP da API People:

      • https://www.googleapis.com/auth/directory.readonly
      • https://www.googleapis.com/auth/userinfo.profile
      • https://www.googleapis.com/auth/contacts.readonly

    2. Clique em Adicionar à tabela.

    3. Clique em Atualizar.

    4. Depois de selecionar os escopos exigidos pelo app, clique em Salvar na página Acesso a dados.

Configurar o cliente MCP

Para adicionar o servidor MCP remoto da API People ao seu cliente MCP, siga as instruções para seu cliente.

CLI do Gemini

Para adicionar o servidor MCP remoto da API People à CLI do Gemini, adicione a configuração do servidor ao arquivo settings.json.

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

    1. No console do Google Cloud, acesse Google Auth Platform > Clientes > Criar cliente.

      Acesse "Criar cliente"

    2. Selecione App para computador como o tipo de aplicativo.

    3. Digite um Nome.

    4. 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/settings.json.

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

    {
  "mcpServers": {
    "people": {
      "httpUrl": "https://people.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [
          "https://www.googleapis.com/auth/directory.readonly",
          "https://www.googleapis.com/auth/userinfo.profile",
          "https://www.googleapis.com/auth/contacts.readonly"
        ]
      }
    }
  }
}

    Substitua:

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

  4. Economize settings.json.

  5. Inicie a CLI do Gemini:

    gemini

  6. Na CLI do Gemini, autentique com o servidor MCP executando o seguinte comando:

    /mcp auth people
    1. Quando solicitado, pressione 1 para abrir uma página de autenticação no navegador. Se você estiver trabalhando por SSH, siga as instruções na CLI.
    2. Faça login na sua Conta do Google.
    3. Analise os escopos do OAuth solicitados e clique em Permitir.
    4. Uma mensagem aparece confirmando que a autenticação foi concluída.

  7. Na CLI do Gemini, execute /mcp list para conferir os servidores MCP configurados e as ferramentas deles.

    A resposta é semelhante a:

    🟢 people - Ready (3 tools)
  Tools:
  - get_user_profile
  - search_contacts
  - search_directory_people

O servidor MCP remoto está pronto para uso na CLI do Gemini.

Claude

Para usar o servidor MCP remoto da API People com o Claude.ai ou o Claude Desktop, é preciso ter o plano Enterprise, Pro, Max ou Team do Claude.

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

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

    1. No console do Google Cloud, acesse Google Auth Platform > 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. 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 para computador, acesse Configurações (ou Configurações de administrador) > Conectores.
    2. Clique em Adicionar conector personalizado.
    3. Insira os detalhes da conexão do produto da API People:
      • Nome do servidor: people.
      • URL do servidor MCP remoto: https://people.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 da API People, insira o seguinte:

  • Nome do servidor: people

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

  • Transporte: HTTP

  • Autenticação: o servidor MCP remoto da API People usa o OAuth 2.0. Para detalhes, consulte Saiba mais sobre autenticação e autorização.

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

Testar o servidor MCP da API People

Depois de configurar o cliente do MCP, você pode verificar a conexão executando alguns comandos de teste.

Pergunte ao cliente do MCP:

  • "De acordo com meu perfil do Google, qual é meu nome?"

    O cliente usa people.get_user_profile para recuperar as informações do seu perfil do Workspace do Google.

Se as ferramentas forem executadas corretamente e você receber respostas relevantes, o servidor MCP da API People estará configurado corretamente.

Solução de problemas

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

Referência da ferramenta

As seguintes ferramentas estão disponíveis para o servidor MCP da API People:

  • get_user_profile
  • search_contacts
  • search_directory_people

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

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

Para reduzir esses riscos, siga estas práticas recomendadas:

  • Use apenas ferramentas confiáveis. Nunca conecte o servidor MCP da API People a aplicativos não confiáveis ou não verificados.
  • Tenha cuidado com entradas não confiáveis. Evite pedir ao cliente do MCP para processar recursos de fontes não verificadas. Essas entradas podem conter instruções ocultas que podem sequestrar sua sessão, permitindo que um invasor modifique, roube ou exclua seus dados.
  • Analise todas as ações. Sempre revise com cuidado as ações realizadas pelo seu cliente de IA em seu nome para garantir que estejam corretas e alinhadas às suas intenções.