Usar o servidor MCP do BigQuery

Neste documento, descrevemos como usar o servidor do protocolo de contexto do modelo (MCP) do BigQuery para se conectar ao BigQuery em aplicativos de IA, como a CLI do Gemini, o modo de agente no Gemini Code Assist, o Claude Code ou em aplicativos de IA que você está desenvolvendo.

O padrão Protocolo de Contexto de Modelo (MCP) padroniza como os modelos de linguagem grandes (LLMs) e os aplicativos ou agentes de IA se conectam a fontes de dados externas. Com os servidores do MCP, é possível usar as ferramentas, os recursos e os comandos deles para realizar ações e receber dados atualizados do serviço de back-end.

Os servidores MCP locais geralmente são executados na sua máquina local e usam os fluxos de entrada e saída padrão (stdio) para comunicação entre serviços no mesmo dispositivo. Os servidores MCP são executados na infraestrutura do serviço e oferecem um endpoint HTTPS para aplicativos de IA para comunicação entre o cliente MCP de IA e o servidor MCP. Para mais informações sobre a arquitetura do MCP, consulte Arquitetura do MCP.

Os servidores do Google e do Google Cloud MCP têm os seguintes recursos e benefícios:

  • Descoberta simplificada e centralizada
  • Endpoints HTTPS globais ou regionais gerenciados
  • Autorização detalhada
  • Segurança opcional de comandos e respostas com a proteção do Model Armor
  • Registro de auditoria centralizado

Para informações sobre outros servidores do MCP e controles de segurança e governança disponíveis para servidores do MCP no Google Cloud, consulte a Visão geral dos servidores do MCP no Google Cloud.

Você pode usar o servidor MCP local do BigQuery pelos seguintes motivos:

  • Você precisa criar uma ferramenta personalizada com uma consulta SQL parametrizada.
  • Você não tem permissão para ativar ou usar o servidor MCP no seu projeto.

Para mais informações sobre como usar nosso servidor MCP local, consulte Conectar LLMs ao BigQuery com o MCP. As seções a seguir se aplicam apenas ao servidor MCP do BigQuery.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  6. Ative a API BigQuery.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

    Para novos projetos, a API BigQuery é ativada automaticamente.

  7. Opcional: ative o faturamento do projeto. Se você não quiser ativar o faturamento ou informar um cartão de crédito, as etapas deste documento ainda funcionarão. O BigQuery fornece um sandbox para executar as etapas. Para mais informações, consulte Ativar o sandbox do BigQuery.

Funções exigidas

Para receber as permissões necessárias para ativar o servidor MCP do BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto em que você quer ativar o servidor MCP do BigQuery:

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

Esses papéis predefinidos contêm as permissões necessárias para ativar o servidor MCP do BigQuery. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para ativar o servidor MCP do BigQuery:

  • Ativar servidores MCP em um projeto:
    • serviceusage.mcppolicy.get
    • serviceusage.mcppolicy.update
  • Faça chamadas de ferramentas do MCP: mcp.tools.call
  • Executar jobs do BigQuery: bigquery.jobs.create
  • Consultar dados do BigQuery: bigquery.tables.getData

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Ativar ou desativar o servidor MCP do BigQuery

É possível ativar ou desativar o servidor MCP do BigQuery em um projeto com o comando gcloud beta services mcp enable. Para mais informações, consulte as seções a seguir.

Ativar o servidor MCP do BigQuery em um projeto

Se você estiver usando projetos diferentes para suas credenciais de cliente, como chaves de conta de serviço, ID do cliente OAuth ou chaves de API, e para hospedar seus recursos, ative o serviço do BigQuery e o servidor MCP do BigQuery nos dois projetos.

Para ativar o servidor BigQuery MCP no seu projeto Google Cloud , execute o seguinte comando:

gcloud beta services mcp enable bigquery.googleapis.com \
    --project=PROJECT_ID

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud

O servidor MCP do BigQuery está ativado para uso no seu projetoGoogle Cloud . Se o serviço do BigQuery não estiver ativado para seu projeto Google Cloud , você vai receber uma solicitação para ativar o serviço antes de ativar o servidor da MCP do BigQuery.

Como prática recomendada de segurança, recomendamos que você ative os servidores MCP apenas para os serviços necessários para o funcionamento do seu aplicativo de IA.

Desativar o servidor MCP do BigQuery em um projeto

Para desativar o servidor BigQuery MCP no seu projeto Google Cloud , execute o seguinte comando:

gcloud beta services mcp disable bigquery.googleapis.com \
    --project=PROJECT_ID

O servidor da MCP do BigQuery está desativado para uso no seu projetoGoogle Cloud .

Autenticação e autorização

Os servidores MCP do BigQuery usam o protocolo OAuth 2.0 com o Identity and Access Management (IAM) para autenticação e autorização. Todas as Google Cloud identidades são compatíveis com a autenticação em servidores MCP.

O servidor MCP do BigQuery não aceita chaves de API.

Escopos OAuth da MCP do BigQuery

O OAuth 2.0 usa escopos e credenciais para determinar se um principal autenticado está autorizado a realizar uma ação específica em um recurso. Para mais informações sobre os escopos do OAuth 2.0 no Google, leia Como usar o OAuth 2.0 para acessar as APIs do Google.

O BigQuery tem os seguintes escopos OAuth da ferramenta MCP:

URI de escopo para a CLI gcloud Descrição
https://www.googleapis.com/auth/bigquery Acessar e gerenciar seus dados no BigQuery e consultar o endereço de e-mail da sua Conta do Google.

Outros escopos podem ser necessários nos recursos acessados durante uma chamada de ferramenta. Para conferir uma lista de escopos necessários para o BigQuery, consulte Escopos do OAuth 2.0 para a API BigQuery v2.

Configurar um cliente MCP para usar o servidor MCP do BigQuery

Programas host, como a CLI do Claude ou do Gemini, podem instanciar clientes MCP que se conectam a um único servidor MCP. Um programa host pode ter vários clientes que se conectam a servidores MCP diferentes. Para se conectar a um servidor MCP, o cliente precisa saber pelo menos o URL dele.

No host, procure uma maneira de se conectar a um servidor MCP. Você vai precisar inserir detalhes sobre o servidor, como nome e URL.

Para o servidor MCP do BigQuery, insira o seguinte conforme necessário:

  • Nome do servidor: servidor MCP do BigQuery
  • URL do servidor ou Endpoint: https://bigquery.googleapis.com/mcp
  • Transporte: HTTP

  • Detalhes de autenticação: suas credenciais Google Cloud , seu ID do cliente e chave secreta do OAuth ou uma identidade e credenciais do agente.

    Os detalhes de autenticação escolhidos dependem de como você quer fazer a autenticação. Para mais informações, consulte Autenticar em servidores do MCP.

Para orientações específicas sobre hosts, consulte:

Para orientações mais gerais, consulte Conectar-se a servidores MCP remotos.

Ferramentas disponíveis

Para conferir detalhes das ferramentas da MCP disponíveis e as descrições delas para o servidor MCP do BigQuery, consulte a referência da MCP do BigQuery.

Limitações

As ferramentas de MCP do BigQuery estão sujeitas às seguintes limitações:

  • A ferramenta execute_sql não é compatível com consultas de tabelas externas do Google Drive.
  • Por padrão, a ferramenta execute_sql limita o tempo de processamento da consulta a três minutos. As consultas que levam mais de três minutos são canceladas automaticamente.
  • Os resultados da consulta são limitados a um máximo de 3.000 linhas.

Ferramentas de lista

Use o MCP Inspector para listar ferramentas ou envie uma solicitação HTTP tools/list diretamente ao servidor MCP do BigQuery. O método tools/list não requer autenticação.

POST /mcp HTTP/1.1
Host: bigquery.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

Exemplos de casos de uso

Confira a seguir exemplos de casos de uso do servidor MCP do BigQuery:

  • Crie fluxos de trabalho que usam insights dos dados do BigQuery para acionar determinadas ações, como criar problemas e escrever e-mails.

  • Use os recursos avançados do BigQuery, como previsão, para insights de ordem superior.

  • Crie uma experiência de conversa para seus usuários com instruções personalizadas do agente.

Comandos de amostra

Use os comandos de exemplo a seguir para receber informações sobre recursos do BigQuery, gerar insights e analisar dados do BigQuery:

  • Liste os conjuntos de dados no projeto PROJECT_ID.
  • Encontre todas as consultas que executei no projeto PROJECT_ID usando o servidor MCP na região REGION. Use a tag goog-mcp-server:true para identificar os jobs de consulta executados pelo servidor MCP.
  • Encontre os principais pedidos por volume de DATASET_ID no projeto PROJECT_ID. Identifique as tabelas adequadas, encontre o esquema correto e mostre os resultados.
  • Crie uma previsão na tabela PROJECT_ID.DATASET_ID.TABLE_ID para os próximos anos. Use COLUMN_NAME como a coluna de dados e COLUMN_NAME como a coluna de carimbo de data/hora. Mostrar as 10 principais previsões.

Nas solicitações, substitua o seguinte:

  • PROJECT_ID: o ID do projeto Google Cloud
  • REGION: o nome da região.
  • DATASET_ID: o nome do conjunto de dados
  • TABLE_ID: o nome da tabela
  • COLUMN_NAME: o nome da coluna

Configurações opcionais de segurança

A MCP apresenta novos riscos e considerações de segurança devido à grande variedade de ações que podem ser realizadas com as ferramentas dela. Para minimizar e gerenciar esses riscos, o Google Cloud oferece padrões e políticas personalizáveis para controlar o uso das ferramentas do MCP na sua organização ou projeto do Google Cloud.

Para mais informações sobre segurança e governança do MCP, consulte Segurança e proteção de IA.

Usar o Model Armor

O Model Armor é um serviço Google Cloud projetado para aumentar a segurança dos seus aplicativos de IA. Ele funciona analisando proativamente os comandos e respostas de LLMs, protegendo contra vários riscos e apoiando práticas de IA responsável. Se você implanta a IA no seu ambiente de nuvem ou em provedores de nuvem externos, o Model Armor pode ajudar a evitar entradas maliciosas, verificar a segurança do conteúdo, proteger dados sensíveis, manter a conformidade e aplicar suas políticas de segurança e proteção de IA de maneira consistente em todo o cenário diversificado de IA.

O Model Armor está disponível apenas em locais regionais específicos. Se o Model Armor estiver ativado para um projeto e uma chamada para esse projeto vier de uma região sem suporte, o Model Armor fará uma chamada entre regiões. Para mais informações, consulte Locais do Model Armor.

Ativar o Model Armor

É necessário ativar as APIs do Model Armor antes de usar o Model Armor.

Console

  1. Ativar a API Model Armor.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  2. Selecione o projeto em que você quer ativar o Model Armor.

gcloud

Antes de começar, siga estas etapas usando a Google Cloud CLI com a API Model Armor:

  1. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. Execute o comando a seguir para definir o endpoint de API do serviço Model Armor.

    gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

    Substitua LOCATION pela região em que você quer usar o Model Armor.

Configurar a proteção para servidores MCP remotos e do Google Google Cloud

Para proteger as chamadas e respostas da ferramenta MCP, use as configurações mínimas do Model Armor. Uma configuração mínima define os filtros de segurança mínimos que se aplicam a todo o projeto. Essa configuração aplica um conjunto consistente de filtros a todas as chamadas e respostas da ferramenta MCP no projeto.

Configure uma configuração de valor mínimo do Model Armor com a limpeza do MCP ativada. Para mais informações, consulte Configurar configurações mínimas do Model Armor.

Confira o exemplo de comando a seguir:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

Substitua PROJECT_ID pelo ID do projeto Google Cloud .

Observe as seguintes configurações:

  • INSPECT_AND_BLOCK: o tipo de aplicação que inspeciona o conteúdo do servidor MCP do Google e bloqueia solicitações e respostas que correspondem aos filtros.
  • ENABLED: a configuração que ativa um filtro ou uma restrição.
  • MEDIUM_AND_ABOVE: o nível de confiança para as configurações do filtro de IA responsável - perigoso. É possível modificar essa configuração, mas valores mais baixos podem resultar em mais falsos positivos. Para mais informações, consulte Níveis de confiança do Model Armor.

Desativar a verificação do tráfego do MCP com o Model Armor

Se você quiser interromper a verificação do tráfego do Google MCP com o Model Armor, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

O Model Armor não vai verificar o tráfego do MCP no projeto.

Controlar o uso do MCP com políticas de negação do IAM

As políticas de negação do Identity and Access Management (IAM) ajudam a proteger Google Cloud servidores MCP remotos. Configure essas políticas para bloquear o acesso indesejado às ferramentas do MCP.

Por exemplo, é possível negar ou permitir o acesso com base em:

  • O diretor
  • Propriedades da ferramenta, como somente leitura
  • O ID do cliente OAuth do aplicativo

Para mais informações, consulte Controlar o uso do MCP com o Identity and Access Management.

Cotas e limites

O servidor MCP do BigQuery não tem cotas próprias. Não há limite para o número de chamadas que podem ser feitas ao servidor do MCP.

Você ainda está sujeito às cotas aplicadas pelas APIs chamadas pelas ferramentas do servidor MCP. Os seguintes métodos de API são chamados pelas ferramentas do servidor MCP:

Ferramenta Método de API Cotas
list_dataset_ids datasets.list Cotas e limites de conjuntos de dados
list_table_ids tables.list Cotas e limites de tabelas
get_dataset_info datasets.get Cotas e limites de conjuntos de dados
get_table_info tables.get Cotas e limites de tabelas
execute_sql jobs.Query Cotas e limites de jobs de consulta

Para mais informações sobre as cotas do BigQuery, consulte Cotas e limites.

A seguir