Usar o servidor MCP remoto do BigQuery

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviçoe aos Termos Adicionais para Produtos de Pré-lançamento de IA Generativa. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Neste documento, descrevemos como usar o servidor do protocolo de contexto do modelo (MCP) remoto 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 do Protocolo de Contexto de Modelo (MCP) padroniza a forma como os modelos de linguagem grandes (LLMs) e os aplicativos ou agentes de IA se conectam a fontes de dados externas. Com os servidores MCP, você pode 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 padrão e saída padrão (stdio) para comunicação entre serviços no mesmo dispositivo. Os servidores MCP remotos 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.

O Google e os servidores MCP remotos têm os seguintes recursos e benefícios: Google Cloud

• 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 MCP e controles de segurança e governança disponíveis para servidores MCP do Google Cloud, consulte a visão geral dos servidores MCP do 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 remoto no seu projeto.

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

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

1. Enable the BigQuery API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

   Para novos projetos, a API BigQuery é ativada automaticamente.

2. 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.
   Observação: se o projeto tiver uma conta de faturamento e você quiser usar o sandbox do BigQuery, desative o faturamento no seu projeto.

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:

• Ative as APIs e os servidores do MCP no projeto: Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)
• Fazer chamadas de ferramentas do MCP: Usuário da ferramenta MCP (roles/mcp.toolUser)
• Executar jobs do BigQuery: Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Consultar dados do BigQuery: Leitor de dados do BigQuery (roles/bigquery.dataViewer)

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
• Fazer 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.

Observação: dependendo da tarefa, pode ser necessário ter outras permissões do BigQuery. Para informações sobre as permissões do BigQuery, consulte Papéis e permissões do IAM do BigQuery.

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 remoto 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 SERVICE \
    --project=PROJECT_ID

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud
• SERVICE: bigquery.googleapis.com (o nome do serviço global do BigQuery)

O servidor MCP remoto 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 MCP remoto 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 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 SERVICE \
    --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 remoto 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 gcloud CLI	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 a CLI 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 remoto, o cliente MCP precisa saber, no mínimo, o URL do servidor MCP remoto.

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

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

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

• Detalhes de autenticação: suas credenciais do 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:

• Configuração do servidor MCP da CLI do Gemini
• Suporte do Claude: como começar a usar conectores personalizados com o MCP remoto

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

Ferramentas disponíveis

As ferramentas do MCP somente leitura têm o atributo mcp.tool.isReadOnly definido como true. Talvez você queira permitir apenas ferramentas somente leitura em determinados ambientes usando sua política da organização.

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.

Ferramentas de lista

Use o inspetor da MCP para listar ferramentas ou envie uma solicitação HTTP tools/list diretamente ao servidor MCP remoto 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 estimativa, 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 de ferramentas de 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.

Model Armor

O Model Armor é um serviço Google Cloud projetado para ajustar a segurança dos seus aplicativos de IA. Ele funciona verificando proativamente 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 mal-intencionadas, 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

Para ativar o Model Armor, siga estas etapas:

1. Ative o Model Armor no seu projeto do Google Cloud .

   gcloud services enable modelarmor.googleapis.com \
       --project=PROJECT_ID
   

   Substitua PROJECT_ID pelo Google Cloud ID do projeto.

2. Configure as configurações mínimas recomendadas para o Model Armor.

   gcloud model-armor floorsettings update \
       --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
       --mcp-sanitization=ENABLED \
       --malicious-uri-filter-settings-enforcement=ENABLED \
       --pi-and-jailbreak-filter-settings-enforcement=ENABLED \
       --pi-and-jailbreak-filter-settings-confidence-level=MEDIUM_AND_ABOVE
   

   Substitua PROJECT_ID pelo Google Cloud ID do projeto.

   O Model Armor é configurado para verificar URLs mal-intencionados e tentativas de injeção de comandos e jailbreak.

   Para mais informações sobre filtros configuráveis do Model Armor, consulte Filtros do Model Armor.

3. Adicione o Model Armor como um provedor de segurança de conteúdo para serviços MCP.

   gcloud beta services mcp content-security add modelarmor.googleapis.com \
       --project=PROJECT_ID
   

   Substitua PROJECT_ID pelo Google Cloud ID do projeto.

4. Confirme se o tráfego do MCP está sendo enviado para o Model Armor.

   gcloud beta services mcp content-security get \
       --project=PROJECT_ID
   

   Substitua PROJECT_ID pelo Google Cloud ID do projeto.

Registro do Model Armor

Para informações sobre registros de auditoria e da plataforma do Model Armor, consulte Geração de registros de auditoria do Model Armor.

Atenção: se uma solicitação falhar, o Model Armor vai registrar todo o payload. Isso pode expor informações sensíveis nos registros.

Desativar o Model Armor em um projeto

Para desativar o Model Armor em um projeto do Google Cloud , execute o seguinte comando:

gcloud beta services mcp content-security remove modelarmor.googleapis.com \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto Google Cloud .

O tráfego do MCP em Google Cloud não é verificado pelo Model Armor no projeto especificado.

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

Se você ainda quiser usar o Model Armor em um projeto, mas quiser interromper a verificação do tráfego do MCP com o Model Armor, execute o seguinte comando:

gcloud model-armor floorsettings update \
    --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
    --mcp-sanitization=DISABLED

Substitua PROJECT_ID pelo ID do projeto Google Cloud .

O Model Armor não vai analisar o tráfego do MCP em Google Cloud.

Controle de MCP no nível da organização

É possível criar políticas da organização personalizadas para controlar o uso de servidores MCP na organização do Google Cloud usando a restrição gcp.managed.allowedMCPService. Para mais informações e exemplos de uso, consulte Controle de acesso com o IAM.

Cotas e limites

O servidor MCP remoto 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

• Leia a documentação de referência do MCP do BigQuery.
• Saiba mais sobre os servidores MCP do Google Cloud.
• Confira os produtos compatíveis do MCP.