Caixa de ferramentas MCP para bancos de dados: como disponibilizar conjuntos de dados do BigQuery para clientes MCP

Toolbox do MCP para bancos de dados:

como disponibilizar conjuntos de dados do BigQuery para clientes do MCP

Sobre este codelab

Último jun. 20, 2025 atualizado

Escrito por Romin Irani

1. Introdução

Neste codelab, você vai usar a Caixa de ferramentas do MCP para bancos de dados para disponibilizar seus conjuntos de dados do BigQuery.

No codelab, você vai usar uma abordagem detalhada da seguinte forma:

1. Identifique um conjunto de dados específico do BigQuery ("Avisos de lançamento do Google Cloud") no programa de conjuntos de dados públicos do BigQuery.
2. Configure a Toolbox do MCP para bancos de dados, que se conecta ao conjunto de dados do BigQuery.
3. Desenvolva um agente usando o Kit de Desenvolvimento de Agentes (ADK) que vai usar o MCP Toolbox para responder às consultas do usuário sobre as notas de lançamento do Google Cloud

O que você aprenderá

• Configure o MCP Toolbox for Databases para expor as notas de lançamento do Google Cloud, um conjunto de dados público do BigQuery, como uma interface MCP para outros clientes MCP (IDEs, ferramentas etc.).

O que você vai aprender

• Analise os conjuntos de dados públicos do BigQuery e escolha um específico.
• Configure a Toolbox do MCP para bancos de dados no conjunto de dados público do BigQuery que você quer disponibilizar para os clientes do MCP.
• Projete e desenvolva um agente usando o Kit de Desenvolvimento de Agentes (ADK) para responder às consultas do usuário.
• Teste o agente e o MCP Toolbox for Databases no ambiente local.

O que é necessário

• Navegador da Web Chrome.
• Um ambiente de desenvolvimento local do Python.

2. Antes de começar

Criar um projeto

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
3. Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com bq. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.

4. Depois de se conectar ao Cloud Shell, verifique se você já está autenticado e se o projeto está definido como seu ID usando o seguinte comando:

gcloud auth list

5. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.

gcloud config list project

6. Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

Consulte a documentação para ver o uso e os comandos gcloud.

3. Conjunto de dados de notas da versão do Google e clientes MCP

Primeiro, vamos conferir as notas de lançamento do Google Cloud, que são atualizadas regularmente na página oficial de notas de lançamento do Google Cloud. Confira uma captura de tela abaixo:

Você pode se inscrever no URL do feed, mas que tal perguntar no nosso Chat com o agente sobre essas notas da versão? Talvez uma consulta simples, como "Atualize as notas de lançamento do Google Cloud".

4. MCP Toolbox for Databases

O MCP Toolbox for Databases é um servidor MCP de código aberto para bancos de dados. Ele foi projetado com qualidade de produção e nível empresarial em mente. Ele permite que você desenvolva ferramentas de maneira mais fácil, rápida e segura, lidando com complexidades como agrupamento de conexões, autenticação e muito mais.

A Toolbox ajuda a criar ferramentas de IA generativa que permitem que os agentes acessem dados no seu banco de dados. A caixa de ferramentas oferece:

• Desenvolvimento simplificado: integre ferramentas ao seu agente em menos de 10 linhas de código, reutilize ferramentas entre vários agentes ou frameworks e implante novas versões de ferramentas com mais facilidade.
• Melhor desempenho: práticas recomendadas, como pooling de conexões, autenticação e muito mais.
• Segurança aprimorada: autenticação integrada para acesso mais seguro aos seus dados
• Observabilidade de ponta a ponta: métricas e rastreamento prontos para uso com suporte integrado ao OpenTelemetry.
• A Toolbox facilita a conexão de bancos de dados a qualquer assistente de IA compatível com MCP, mesmo aqueles que estão no seu ambiente de desenvolvimento integrado.

A caixa de ferramentas fica entre o framework de orquestração do aplicativo e o banco de dados, fornecendo um plano de controle usado para modificar, distribuir ou invocar ferramentas. Ele simplifica o gerenciamento das ferramentas, fornecendo um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem precisar implantar novamente o aplicativo.

Para resumir em palavras simples:

1. A Toolbox do MCP está disponível como uma imagem de contêiner binária ou pode ser criada a partir da fonte.
2. Ele expõe um conjunto de ferramentas que você configura usando um arquivo tools.yaml. As ferramentas podem se conectar às suas fontes de dados. Você pode conferir as várias fontes de dados compatíveis : AlloyDB, BigQuery etc.
3. Como essa caixa de ferramentas agora oferece suporte ao MCP, você tem automaticamente um endpoint do MCP Server que pode ser consumido pelos agentes (IDEs) ou pode usá-los ao desenvolver seus aplicativos de agente usando vários frameworks, como o Kit de Desenvolvimento de Agentes (ADK).

O foco desta postagem do blog será nas áreas destacadas abaixo:

Em resumo, vamos criar uma configuração na Toolbox do MCP para bancos de dados que saiba como se conectar ao nosso conjunto de dados do BigQuery. Em seguida, vamos desenvolver um agente usando o Kit de Desenvolvimento de Agentes (ADK), que será integrado ao endpoint do MCP Toolbox e permitirá que enviemos consultas naturais para fazer perguntas sobre nosso conjunto de dados. Pense nisso como um aplicativo de agente que você está desenvolvendo, que sabe como se comunicar com seu conjunto de dados do BigQuery e executa algumas consultas.

5. Notas da versão do conjunto de dados do BigQuery para o Google Cloud

O Programa de conjuntos de dados públicos do Google Cloud disponibiliza uma variedade de conjuntos de dados para seus aplicativos. Um desses conjuntos de dados é o banco de dados de notas de lançamento do Google Cloud. Esse conjunto de dados fornece as mesmas informações da página oficial de notas de lançamento do Google Cloud e está disponível como um conjunto de dados pesquisável publicamente.

Como teste, simplesmente valide o conjunto de dados executando uma consulta simples mostrada abaixo:

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

Isso me mostra uma lista de registros do conjunto de dados "Release Notes" que foram publicados nos últimos sete dias.

Substitua por qualquer outro conjunto de dados e as respectivas consultas e parâmetros que você quiser. Agora, precisamos configurar isso como uma fonte e uma ferramenta de dados no MCP Toolbox for Databases. Vamos ver como fazer isso.

6. Como instalar o MCP Toolbox for Databases

Abra um terminal na sua máquina local e crie uma pasta chamada mcp-toolbox.

mkdir mcp-toolbox

Acesse a pasta mcp-toolbox usando o comando mostrado abaixo:

cd mcp-toolbox

Instale a versão binária do MCP Toolbox for Databases usando o script abaixo. O comando abaixo é para Linux, mas, se você estiver usando Mac ou Windows, verifique se está fazendo o download do binário correto. Confira a página de lançamentos do seu sistema operacional e arquitetura e faça o download do binário correto.

export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Agora temos a versão binária da caixa de ferramentas pronta para uso. A próxima etapa é configurar a caixa de ferramentas com nossas fontes de dados e outras configurações.

7. Como configurar o MCP Toolbox for Databases

Agora, precisamos definir o conjunto de dados e as ferramentas do BigQuery no arquivo tools.yaml, que é necessário para a Toolbox do MCP para banco de dados. O arquivo tools.yaml é a principal maneira de configurar a Toolbox.

Crie um arquivo chamado tools.yaml na mesma pasta, ou seja, mcp-toolbox, cujo conteúdo é mostrado abaixo.

Você pode usar o editor nano disponível no Cloud Shell. O comando nano é o seguinte: "nano tools.yaml".

Substitua o valor YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud.

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - search_release_notes_bq

Vamos entender o arquivo em resumo:

1. As fontes representam as diferentes origens de dados com que uma ferramenta pode interagir. Uma fonte representa uma fonte de dados com que uma ferramenta pode interagir. É possível definir as origens como um mapa na seção "sources" do arquivo tools.yaml. Normalmente, uma configuração de origem contém todas as informações necessárias para se conectar e interagir com o banco de dados. No nosso caso, definimos uma fonte do BigQuery my-bq-source e você precisa informar o ID do projeto do Google Cloud. Para mais informações, consulte a referência Origens.
2. As ferramentas definem as ações que um agente pode realizar, como ler e gravar em uma origem. Uma ferramenta representa uma ação que o agente pode realizar, como executar uma instrução SQL. É possível definir as ferramentas como um mapa na seção "tools" do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para funcionar. No nosso caso, definimos uma única ferramenta search_release_notes_bq. Isso faz referência à fonte do BigQuery my-bq-source que definimos na primeira etapa. Ele também tem a instrução e a instrução que serão usadas pelos clientes do agente de IA. Para mais informações, consulte a referência de ferramentas.
3. Por fim, temos o conjunto de ferramentas, que permite definir grupos de ferramentas que você quer carregar juntos. Isso pode ser útil para definir grupos diferentes com base no agente ou no aplicativo. No nosso caso, temos uma definição de conjunto de ferramentas em que definimos apenas uma ferramenta search_release_notes_bq. Você pode ter mais de um conjunto de ferramentas, que tem uma combinação de ferramentas diferentes.

No momento, definimos apenas uma ferramenta que recebe as notas da versão dos últimos sete dias, de acordo com a consulta. Mas você também pode ter várias combinações com parâmetros.

Confira mais detalhes de configuração ( Origem, Ferramentas) na configuração da fonte de dados do BigQuery na Caixa de ferramentas do MCP para bancos de dados.

8. Como testar o MCP Toolbox for Databases

Fizemos o download e configuramos a Toolbox com o arquivo tools.yaml na pasta mcp-toolbox. Vamos executar primeiro localmente.

Execute o seguinte comando:

./toolbox --tools-file="tools.yaml"

Se a execução for bem-sucedida, você verá a inicialização do servidor com um exemplo de saída semelhante ao abaixo:

2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources." 
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices." 
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools." 
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets." 
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!" 

O servidor da Toolbox do MCP é executado por padrão na porta 5000. Se a porta 5000 já estiver em uso, use outra (7000, por exemplo) conforme o comando mostrado abaixo. Use 7000 em vez da porta 5000 nos comandos seguintes.

./toolbox --tools-file "tools.yaml" --port 7000

Vamos usar o Cloud Shell para testar isso.

Clique em "Visualização da Web" no Cloud Shell, conforme mostrado abaixo:

Clique em Change port e defina a porta como 5000, conforme mostrado abaixo, e clique em "Change and Preview".

Isso vai gerar o seguinte resultado:

No URL do navegador, adicione o seguinte ao final do URL:

/api/toolset

Isso vai mostrar as ferramentas que estão configuradas no momento. Confira um exemplo de saída abaixo:

{
  "serverVersion": "0.7.0+binary.linux.amd64.714d990c34ee990e268fac1aa6b89c4883ae5023",
  "tools": {
    "search_release_notes_bq": {
      "description": "Use this tool to get information on Google Cloud Release Notes.\n",
      "parameters": [],
      "authRequired": []
    }
  }
}

O MCP Toolkit for Databases descreve uma maneira Pythonic de validar e testar as ferramentas, que está documentada aqui. Vamos pular essa etapa e passar diretamente para o Kit de Desenvolvimento de Agentes (ADK, na sigla em inglês) na próxima seção, que vai usar essas ferramentas.

9. Como criar nosso agente com o Kit de Desenvolvimento de Agentes (ADK)

Instalar o Kit de desenvolvimento de agentes (ADK)

Abra uma nova guia do terminal no Cloud Shell e crie uma pasta chamada my-agents da seguinte maneira. Navegue até a pasta my-agents também.

mkdir my-agents
cd my-agents

Agora, vamos criar um ambiente virtual do Python usando venv da seguinte maneira:

python -m venv .venv

Ative o ambiente virtual da seguinte maneira:

source .venv/bin/activate

Instale o ADK e os pacotes do MCP Toolbox for Databases com a dependência do LangChain da seguinte maneira:

pip install google-adk toolbox-core

Agora você poderá invocar o utilitário adk da seguinte maneira.

adk

Uma lista de comandos vai aparecer.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --help  Show this message and exit.

Commands:
  api_server  Starts a FastAPI server for agents.
  create      Creates a new app in the current folder with prepopulated agent template.
  deploy      Deploys agent to hosted environments.
  eval        Evaluates an agent given the eval sets.
  run         Runs an interactive CLI for a certain agent.
  web         Starts a FastAPI server with Web UI for agents.

Como criar nosso primeiro aplicativo de agente

Agora vamos usar adk para criar um esqueleto para o aplicativo do agente de notas de lançamento do Google Cloud usando o comando adk create com um nome de app **(gcp-releasenotes-agent-app)**conforme mostrado abaixo.

adk create gcp-releasenotes-agent-app

Siga as etapas e selecione o seguinte:

• Modelo Gemini para escolher um modelo para o agente raiz.
• Escolha a Vertex AI para o back-end.
• O ID e a região padrão do projeto do Google vão aparecer. Selecione o padrão.

Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_GOOGLE_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py

Observe a pasta em que um modelo padrão e os arquivos necessários para o agente foram criados.

Primeiro, o arquivo .env. O conteúdo é mostrado abaixo:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Os valores indicam que vamos usar o Gemini pela Vertex AI, além dos respectivos valores para o ID e o local do projeto do Google Cloud.

Em seguida, temos o arquivo __init__.py, que marca a pasta como um módulo e tem uma única instrução que importa o agente do arquivo agent.py.

from . import agent

Por fim, vamos conferir o arquivo agent.py. O conteúdo é mostrado abaixo:

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

Esse é o agente mais simples que você pode programar com o ADK. De acordo com a página da documentação do ADK, um agente é uma unidade de execução independente projetada para agir de forma autônoma e alcançar objetivos específicos. Os agentes podem realizar tarefas, interagir com usuários, usar ferramentas externas e se coordenar com outros agentes.

Especificamente, um LLMAgent, comumente conhecido como "Agente", usa modelos de linguagem grandes (LLMs) como mecanismo principal para entender a linguagem natural, raciocinar, planejar, gerar respostas e decidir dinamicamente como proceder ou quais ferramentas usar, tornando-os ideais para tarefas flexíveis e centradas na linguagem. Saiba mais sobre os agentes de LLM aqui.

Isso conclui o scaffolding para gerar um agente básico usando o Kit de Desenvolvimento de Agentes (ADK). Agora vamos conectar nosso agente à Toolbox do MCP para que ele possa usar essa ferramenta para responder às consultas do usuário (neste caso, as notas de lançamento do Google Cloud).

10. Como conectar nosso agente às ferramentas

Vamos conectar esse agente às ferramentas. No contexto do ADK, uma ferramenta representa um recurso específico fornecido a um agente de IA, permitindo que ele realize ações e interaja com o mundo além das principais habilidades de geração de texto e raciocínio.

No nosso caso, vamos equipar nosso agente com as ferramentas que configuramos no MCP Toolbox for Databases.

Modifique o arquivo agent.py com o seguinte código. Estamos usando a porta padrão 5000 no código, mas se você estiver usando um número de porta alternativo, use esse número.

from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient

toolbox = ToolboxSyncClient("http://127.0.0.1:5000")

# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')

root_agent = Agent(
    name="gcp_releasenotes_agent",
    model="gemini-2.0-flash",
    description=(
        "Agent to answer questions about Google Cloud Release notes."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
    ),
    tools=tools,
)

Agora podemos testar o agente que vai buscar dados reais do conjunto de dados do BigQuery configurado com a Toolbox do MCP para bancos de dados.

Para fazer isso, siga esta sequência:

Em um terminal do Cloud Shell, inicie a MCP Toolbox for Databases. Talvez ele já esteja em execução localmente na porta 5000, como testamos anteriormente. Caso contrário, execute o seguinte comando (da pasta mcp-toolbox) para iniciar o servidor:

./toolbox --tools_file "tools.yaml"

O ideal é que você veja uma saída informando que o servidor conseguiu se conectar às nossas fontes de dados e carregou o conjunto de ferramentas. Confira um exemplo de saída abaixo:

./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources." 
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices." 
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools." 
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets." 
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!" 

Depois que o servidor MCP for iniciado, em outro terminal, inicie o agente pelo comando adk run (da pasta my-agents) mostrado abaixo. Também é possível usar o comando adk web, se preferir.

$ adk run gcp-releasenotes-agent-app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.

[user]: get me the google cloud release notes


[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.

Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14

Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13

Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13

Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13

Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13

Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13

Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......

O agente está usando a ferramenta que configuramos na Toolbox do MCP para bancos de dados (search_release_notes_bq), extrai os dados do conjunto de dados do BigQuery e formata a resposta.

11. Parabéns

Parabéns! Você configurou a Toolbox do MCP para bancos de dados e configurou um conjunto de dados do BigQuery para acesso em clientes do MCP.

Documentos de referência

• MCP Toolbox for Databases
• Conjuntos de dados públicos do BigQuery