Conectar-se a um agente de dados usando o MCP

Como administrador de uma plataforma agêntica de terceiros (como Claude Code, Claude Cowork ou ChatGPT) ou gerenciada pelo Google (como o Gemini Enterprise), é possível configurar uma conexão personalizada do Protocolo de Contexto de Modelo (MCP) com o servidor MCP remoto da API Análise conversacional (https://geminidataanalytics.googleapis.com/mcp). Conectar sua plataforma agêntica a esse servidor permite que o agente raiz da plataforma descubra e consulte agentes de dados especializados em nome dos usuários empresariais.

O servidor MCP remoto da API Análise conversacional usa um fluxo do OAuth 2.0 de três etapas para propagar as credenciais do usuário final (EUC) para o BigQuery. Essa propagação garante que as solicitações de descoberta do agente e as consultas do BigQuery sejam executadas com a identidade do usuário autenticado e respeitem as permissões do Identity and Access Management (IAM) e as políticas de governança de dados. Os agentes de dados baseados no Looker não recebem credenciais de usuário final. Em vez disso, as consultas exigem credenciais de cliente da API Looker separadas (consulte Autenticação para agentes de dados baseados no Looker).

Para uma visão geral da arquitetura de como os agentes raiz (o principal agente de orquestração que recebe as solicitações do usuário) se comunicam com o servidor MCP remoto, consulte Servidor MCP remoto da API Análise conversacional.

Antes de começar

Antes de configurar a conexão do MCP na sua plataforma de agentes, conclua os seguintes pré-requisitos:

  1. No seu Google Cloud projeto, ative as APIs necessárias para a API Análise conversacional e o BigQuery.
  2. Verifique se os operadores de dados criaram e configuraram um ou mais agentes de dados no projeto do Google Cloud , incluindo descrições claras das fontes de dados que cada agente pode acessar e das perguntas que ele pode responder.
  3. Verifique se os usuários empresariais que vão se autenticar pela conexão do MCP têm os papéis do IAM necessários e acesso de leitura aos conjuntos de dados de destino e ao agente.

Funções exigidas

Para receber as permissões necessárias para autenticar pelo servidor MCP remoto e consultar agentes de dados, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar credenciais e escopos do OAuth 2.0

Para permitir que sua plataforma de agentes autentique usuários e encaminhe as credenciais deles para o servidor MCP remoto da API Análise conversacional, crie credenciais do OAuth 2.0 (um ID do cliente e uma chave secreta do cliente) no projeto do Google Cloud .

Siga as etapas padrão em Como usar o OAuth 2.0 para acessar as APIs do Google para configurar sua tela de permissão OAuth e criar um ID do cliente OAuth 2.0 na página de credenciais do console doGoogle Cloud . Ao configurar suas credenciais, aplique as seguintes configurações específicas para a integração do MCP da API Análise conversacional:

  1. Público-alvo: se a organização usa o Google Workspace, selecione Interno. Essa seleção restringe o acesso aos usuários da sua organização, evita a necessidade de verificação de apps OAuth para escopos sensíveis e garante que as políticas de controle de acesso a apps do Google Workspace não bloqueiem a autenticação dos usuários.
  2. Tipo de aplicativo e URI de redirecionamento: selecione Aplicativo da Web como o tipo de aplicativo e adicione o URI de redirecionamento autorizado exigido pela plataforma de agentes (por exemplo, https://vertexaisearch.cloud.google.com/oauth-redirect ao configurar um conector MCP personalizado no Gemini Enterprise).
  3. Escopos do OAuth: configure a tela de permissão OAuth e o cliente para solicitar os dois escopos a seguir, de modo que o agente raiz tenha permissão para chamar as ferramentas da API Análise conversacional e executar consultas somente leitura do BigQuery em nome do usuário:
    • Escopo do Gemini Data Analytics: https://www.googleapis.com/auth/geminidataanalytics
    • Escopo somente leitura do BigQuery: https://www.googleapis.com/auth/bigquery.readonly
  4. Copie e armazene com segurança o ID do cliente e a chave secreta do cliente gerados.

Configurar a conexão personalizada do MCP

Depois de gerar o ID do cliente e a chave secreta do cliente do OAuth 2.0, registre uma conexão MCP personalizada (ou conector MCP personalizado) nas configurações de administração da sua plataforma agêntica:

  1. Na sua plataforma de agentes, crie uma nova conexão de servidor MCP personalizada e especifique os seguintes valores de configuração:

    Configuração Valor
    URL do servidor MCP https://geminidataanalytics.googleapis.com/mcp
    Método de autenticação OAuth 2.0
    URL de autorização https://accounts.google.com/o/oauth2/v2/auth
    Parâmetros de URL de autorização

    &access_type=offline&prompt=consent

    Use essa string de parâmetro se a plataforma exigir tokens de atualização off-line para sessões de usuário.

    URL do token https://oauth2.googleapis.com/token
    Escopos

    https://www.googleapis.com/auth/geminidataanalytics

    https://www.googleapis.com/auth/bigquery.readonly

    Se a plataforma espera uma única string separada por espaços, insira:

    https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly

    ID do cliente CLIENT_ID (o ID do cliente OAuth 2.0 que você criou na seção anterior)
    Chave secreta do cliente CLIENT_SECRET (a chave secreta do cliente OAuth 2.0 que você criou na seção anterior)
  2. Verifique a conexão OAuth na sua plataforma, se solicitado. Quando a tela de permissão do Google for aberta, faça login e confirme se o aplicativo solicita acesso somente leitura ao Gemini Data Analytics e ao BigQuery.

  3. Sincronize ou recarregue as ferramentas (ações) da conexão MCP na sua plataforma para que o cliente MCP chame tools/list em https://geminidataanalytics.googleapis.com/mcp para importar os esquemas de ferramentas (como list_data_agents, get_data_agent e chat) e verifique se as ferramentas importadas estão ativadas.

Configurar instruções de comando para o agente raiz

As ferramentas do MCP da API Análise conversacional (list_data_agents, get_data_agent e chat) exigem um ID do projeto do Google Cloud e um local de destino (por exemplo, projects/PROJECT_ID/locations/LOCATION). Como os usuários corporativos geralmente não sabem qual ID do projeto do Google Cloud hospeda os agentes de dados da sua organização, forneça o ID do projeto de destino e o local nas instruções personalizadas do sistema ou na configuração de habilidades do agente raiz. Isso impede que o agente raiz solicite que os usuários comerciais forneçam um ID do projeto ao fazer uma pergunta sobre dados.

Adicionar instruções do sistema para descoberta e roteamento de agentes

Adicione as instruções a seguir ao comando do sistema ou às instruções personalizadas do agente raiz, substituindo PROJECT_ID pelo ID do projeto do Google Cloude LOCATION pelo local do recurso (como global, us ou eu):

When answering questions about enterprise data using the Conversational
Analytics MCP tools, always use the Google Cloud project ID
"PROJECT_ID" and location "LOCATION" (resource path
"projects/PROJECT_ID/locations/LOCATION"). Do not ask the user to
provide a Google Cloud project ID or location.

To answer a user's data question:
1. Call list_data_agents for "projects/PROJECT_ID/locations/LOCATION"
   to discover the available data agents and review their descriptions.
2. If you need additional context about a candidate agent's connected tables or
   verified queries, call get_data_agent for that agent.
3. Call the chat tool passing parent ("projects/PROJECT_ID/locations/LOCATION"),
   dataAgentContext with the full agent resource name
   ("projects/PROJECT_ID/locations/LOCATION/dataAgents/<var>AGENT_ID</var>"),
   and the user's question in messages.
4. If the user asks about a specific BigQuery table that isn't connected to any
   of the available data agents, call the chat tool and pass the table directly
   as inline context instead of using a data agent. Pass parent
   ("projects/PROJECT_ID/locations/LOCATION"),
   inlineContext with a datasourceReferences.bq.tableReferences entry for the
   table (projectId, datasetId, and tableId), and the user's question in
   messages.

Autenticação para agentes de dados com tecnologia do Looker

Se os agentes de dados se conectarem às Análises do Looker, as solicitações para a ferramenta chat precisarão incluir um bloco credentials com as credenciais da API Looker (um ID do cliente e uma chave secreta do cliente), porque o Looker gerencia a autenticação de forma independente do IAM.

Ao configurar sua plataforma agêntica para agentes de dados com tecnologia do Looker, siga estas práticas recomendadas:

  • Não peça secrets aos usuários: configure o agente raiz para nunca pedir que os usuários finais colem ou forneçam credenciais da API Looker no chat.
  • Use uma conta de usuário dedicada da API Looker: crie um usuário dedicado da API Looker com permissões de privilégio mínimo que tenham como escopo apenas os modelos e as Análises de que o agente de dados precisa.
  • Injetar credenciais fora do contexto do modelo: configure sua plataforma, o middleware do cliente MCP ou a camada de proxy para injetar credenciais da API Looker no payload da solicitação chat na camada de transporte ou de execução de ferramentas. Não coloque a chave secreta do cliente nas instruções de comando ou no histórico de conversas do agente raiz.

Padrões de injeção de credenciais para plataformas agênticas

Para manter os secrets fora da janela de contexto do modelo, as plataformas geralmente injetam credenciais do Looker usando uma das seguintes abordagens:

  • Middleware do cliente MCP ou interceptação de proxy: em plataformas que oferecem suporte a middleware de solicitação, gateways de API ou hooks de interceptação de ferramentas, o agente raiz gera a chamada de ferramenta chat contendo apenas os parâmetros semânticos (parent, dataAgentContext e messages). A camada de middleware intercepta a solicitação JSON-RPC de saída antes que ela chegue a https://geminidataanalytics.googleapis.com/mcp, lê as credenciais de um repositório de secrets seguro ou de variáveis de ambiente e preenche o objeto credentials.
  • Definições de ferramentas encapsuladas: em frameworks de agentes personalizados (como o Kit de Desenvolvimento de Agente (ADK) ou orquestradores Python personalizados), exponha uma versão encapsulada da ferramenta chat ao agente raiz que omite o parâmetro credentials do esquema da ferramenta. O gerenciador de execução do wrapper anexa o bloco credentials de forma programática de uma configuração segura antes de encaminhar a chamada para o servidor MCP da API Análise conversacional.

O exemplo a seguir mostra o payload completo da solicitação JSON-RPC que o cliente do MCP envia ao servidor MCP remoto para a ferramenta chat. Enquanto o modelo gera os parâmetros parent, dataAgentContext e messages, a plataforma host ou o middleware do cliente MCP preenche o objeto credentials antes de enviar a solicitação:

{
  "parent": "projects/PROJECT_ID/locations/LOCATION",
  "dataAgentContext": {
    "dataAgent": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
  },
  "credentials": {
    "oauth": {
      "secret": {
        "clientId": "LOOKER_CLIENT_ID",
        "clientSecret": "LOOKER_CLIENT_SECRET"
      }
    }
  },
  "messages": [
    {
      "userMessage": {
        "text": "USER_QUESTION"
      }
    }
  ]
}

Substitua os valores de exemplo da seguinte forma:

  • PROJECT_ID: ID do projeto do Google Cloud
  • LOCATION: o local dos recursos da API de Análise conversacional (por exemplo, global)
  • AGENT_ID: o ID do agente de dados do Looker
  • LOOKER_CLIENT_ID: o ID do cliente do usuário da API Looker
  • LOOKER_CLIENT_SECRET: a chave secreta do cliente para o usuário da API Looker
  • USER_QUESTION: o comando ou a pergunta a ser enviada ao agente de dados.

Verificar a conexão com um comando de teste

Depois de vincular a conexão personalizada do MCP ao aplicativo do agente, abra a interface de chat da plataforma, autorize a sessão do usuário quando solicitado e envie um comando de teste para confirmar que o agente raiz pode invocar as ferramentas do MCP da API Análise conversacional e consultar o BigQuery usando suas credenciais delegadas.

Se você configurou as instruções do sistema na seção anterior, faça uma pergunta diretamente aos seus agentes de dados ou execute uma consulta de teste em um conjunto de dados público do BigQuery especificando o projeto, o local e o conjunto de dados no comando:

What are the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales?

Você também pode instruir explicitamente o agente raiz a chamar a ferramenta chat do seu conector MCP (CONNECTOR_NAME):

Use the chat tool from CONNECTOR_NAME to find the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales.

Substitua os valores de exemplo da seguinte forma:

  • PROJECT_ID: o ID do Google Cloud projeto em que você ativou a API Análise conversacional.
  • LOCATION: o local dos recursos da API de Análise conversacional (por exemplo, global)
  • CONNECTOR_NAME: o nome que você atribuiu à conexão personalizada do MCP na sua plataforma de agentes (por exemplo, ca-mcp-prod)

A seguir