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

1. Introdução

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

Durante o codelab, você vai usar uma abordagem gradual da seguinte forma:

1. Identifique um conjunto de dados específico do BigQuery ("Notas da versão do Google Cloud") no programa de conjuntos de dados públicos do BigQuery.
2. Configure a caixa de ferramentas 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 utilizar a caixa de ferramentas do MCP para responder a consultas do usuário sobre as notas da versão do Google Cloud.

O que você aprenderá

• Configure a MCP Toolbox for Databases para expor as notas da versão do Google Cloud, um conjunto de dados público do BigQuery, como uma interface do MCP para outros clientes do 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 caixa de ferramentas do MCP para bancos de dados no conjunto de dados público do BigQuery que queremos disponibilizar aos 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 a 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 sua conta já está autenticada e se o projeto está configurado com seu ID do projeto 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 do 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 e se pudéssemos simplesmente perguntar no chat do agente sobre essas notas da versão? Talvez uma consulta simples como "Me atualize sobre as notas da versão do Google Cloud".

4. MCP Toolbox for Databases

A MCP Toolbox for Databases é um servidor MCP de código aberto para bancos de dados. Ela foi projetada com qualidade de produção e nível empresarial em mente. Ele permite desenvolver ferramentas com mais facilidade, rapidez e segurança, lidando com complexidades como pool de conexões, autenticação e muito mais.

A caixa de ferramentas ajuda você a criar ferramentas de IA generativa que permitem que seus 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 reforçada: 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 caixa de ferramentas facilita a conexão de bancos de dados a qualquer assistente de IA compatível com o 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 suas ferramentas ao fornecer um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem precisar reimplantar o aplicativo.

Para resumir em palavras simples:

1. A caixa de ferramentas do MCP está disponível como um binário, uma imagem de contêiner ou pode ser criada do código-fonte.
2. Ele expõe um conjunto de ferramentas que você configura usando um arquivo tools.yaml. As ferramentas podem ser consideradas como uma conexão à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 é compatível com o MCP, você tem automaticamente um endpoint do servidor MCP que pode ser usado pelos agentes (IDEs) ou durante o desenvolvimento de aplicativos de agente usando várias estruturas, como o Kit de Desenvolvimento de Agentes (ADK).

Nesta postagem do blog, vamos focar nas áreas destacadas abaixo:

Em resumo, vamos criar uma configuração na caixa de ferramentas do MCP para bancos de dados que sabe 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 se integra ao endpoint da caixa de ferramentas do MCP e permite enviar consultas naturais para perguntar sobre nosso conjunto de dados. Pense nisso como um aplicativo de agente que você está desenvolvendo e que sabe como se comunicar com seu conjunto de dados do BigQuery e executar algumas consultas.

5. Conjunto de dados do BigQuery para as notas da versão do 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 das notas da versão do Google Cloud. Esse conjunto de dados fornece as mesmas informações da página da Web oficial das notas da versão do Google Cloud e está disponível como um conjunto de dados consultável publicamente.

Como um teste, basta validar 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 dá uma lista de registros do conjunto de dados "Notas da versão" que foram publicados nos últimos sete dias.

Substitua por qualquer outro conjunto de dados, consultas e parâmetros que você quiser. Agora, basta configurar isso como uma fonte de dados e uma ferramenta na 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 com o comando abaixo:

cd mcp-toolbox

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

export VERSION=0.13.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 a MCP Toolbox for Databases

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

Crie um arquivo chamado tools.yaml na mesma pasta, ou seja, mcp-toolbox. O conteúdo dele é 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 brevemente:

1. As fontes representam as diferentes origens de dados com que uma ferramenta pode interagir. Uma origem representa uma fonte de dados com que uma ferramenta pode interagir. É possível definir 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 origem do BigQuery my-bq-source, e você precisa fornecer o ID do seu projeto do Google Cloud. Para mais informações, consulte a referência Fontes.
2. As ferramentas definem as ações que um agente pode realizar, como ler e gravar em uma fonte. Uma ferramenta representa uma ação que o agente pode realizar, como executar uma instrução SQL. É possível definir ferramentas como um mapa na seção "tools" do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para agir. No nosso caso, definimos uma única ferramenta search_release_notes_bq. Isso faz referência à origem do BigQuery my-bq-source que definimos na primeira etapa. Ela também tem a declaraçã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 juntas. Isso pode ser útil para definir diferentes grupos 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 a MCP Toolbox for Databases

Fizemos o download e configuramos a caixa de ferramentas com o arquivo tools.yaml na pasta mcp-toolbox. Primeiro, vamos executar o app localmente.

Execute o seguinte comando:

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

Se a execução for bem-sucedida, você vai ver uma inicialização do servidor com uma saída de exemplo semelhante a esta:

2025-09-08T03:56:45.772489914Z INFO "Initialized 1 sources." 
2025-09-08T03:56:45.772682659Z INFO "Initialized 0 authServices." 
2025-09-08T03:56:45.772735103Z INFO "Initialized 1 tools." 
2025-09-08T03:56:45.772774639Z INFO "Initialized 2 toolsets." 
2025-09-08T03:56:45.777711644Z INFO "Server ready to serve!"  

Por padrão, o servidor da caixa de ferramentas do MCP é executado na porta 5000. Se você descobrir que a porta 5000 já está em uso, use outra porta (por exemplo, 7000), conforme o comando mostrado abaixo. Use 7000 em vez da porta 5000 nos comandos subsequentes.

./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 Alterar porta, defina a porta como 5000, conforme mostrado abaixo, e clique em "Alterar e visualizar".

Isso vai gerar a seguinte saída:

No URL do navegador, adicione o seguinte ao final:

/api/toolset

Isso vai abrir as ferramentas configuradas no momento. Confira um exemplo de saída abaixo:

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

Testar as ferramentas na interface do MCP Toolbox for Databases

A caixa de ferramentas oferece uma interface visual (IU da caixa de ferramentas) para interagir diretamente com as ferramentas modificando parâmetros, gerenciando cabeçalhos e executando chamadas, tudo em uma interface da Web simples.

Para testar isso, execute o comando anterior que usamos para iniciar o servidor da caixa de ferramentas com uma opção --ui.

Para fazer isso, encerre a instância anterior do servidor da caixa de ferramentas MCP para bancos de dados que você pode estar executando e execute o seguinte comando:

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

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 e as ferramentas. Confira abaixo um exemplo de saída. Você vai notar que ela menciona que a interface da caixa de ferramentas está funcionando.

2025-09-08T03:59:34.856476253Z INFO "Initialized 1 sources." 
2025-09-08T03:59:34.856546526Z INFO "Initialized 0 authServices." 
2025-09-08T03:59:34.856577586Z INFO "Initialized 1 tools." 
2025-09-08T03:59:34.856641568Z INFO "Initialized 2 toolsets." 
2025-09-08T03:59:34.86133344Z INFO "Server ready to serve!" 
2025-09-08T03:59:34.861366205Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui" 

Clique no URL da interface e verifique se você tem /ui no final do URL. Isso vai mostrar uma interface como esta:

Clique na opção "Ferramentas" à esquerda para ver as ferramentas configuradas. No nosso caso, deve haver apenas uma, ou seja, search_release_notes_bq, conforme mostrado abaixo:

Basta clicar nas ferramentas (search_release_notes_bq) para abrir uma página em que você pode testar a ferramenta. Como não há parâmetros para fornecer, basta clicar em Executar ferramenta para ver o resultado. Confira um exemplo de execução abaixo:

O MCP Toolkit for Databases também descreve uma maneira Pythonic de validar e testar as ferramentas, que está documentada aqui. Vamos pular essa parte e passar direto para o Kit de desenvolvimento de agentes (ADK) na próxima seção, que vai usar essas ferramentas.

9. Como escrever nosso agente com o Kit de Desenvolvimento de Agente (ADK)

Instalar o Kit de Desenvolvimento de Agente (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 Python virtual 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ê pode 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 scaffolding para o aplicativo do agente de notas da versão do Google Cloud usando o comando adk create com o nome do app **(gcp-releasenotes-agent-app)**, conforme mostrado abaixo.

adk create gcp-releasenotes-agent-app

Siga as etapas e selecione o seguinte:

• Modelo do 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 dele é 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 com os respectivos valores do ID e 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 escrever com o ADK. Na 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 metas específicas. Os agentes podem realizar tarefas, interagir com usuários, usar ferramentas externas e se coordenar com outros agentes.

Especificamente, um LLMAgent, geralmente conhecido como Agent, 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, o que os torna ideais para tarefas flexíveis e centradas na linguagem. Saiba mais sobre os agentes de LLM neste link.

Isso conclui nosso scaffolding para gerar um agente básico usando o Agent Development Kit (ADK). Agora vamos conectar nosso agente à caixa de ferramentas do MCP para que ele possa usar essa ferramenta e responder às consultas do usuário (neste caso, serão as notas da versão do Google Cloud).

10. Conectar nosso agente a ferramentas

Vamos conectar esse agente às ferramentas agora. No contexto do ADK, uma ferramenta representa uma capacidade específica fornecida a um agente de IA, permitindo que ele execute ações e interaja com o mundo além das habilidades básicas de geração de texto e raciocínio.

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

Modifique o arquivo agent.py com o seguinte código. Observe que 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 nosso conjunto de dados do BigQuery, configurado com a caixa de ferramentas 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 sendo executado localmente na porta 5000, como testamos antes. Se não estiver, execute o seguinte comando (na 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 e as 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 com o comando adk run (da pasta my-agents) mostrado abaixo. Se preferir, use o comando adk web.

$ 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 caixa de ferramentas do MCP para bancos de dados (search_release_notes_bq) e recupera os dados do conjunto de dados do BigQuery, formatando a resposta de acordo.

11. Parabéns

Parabéns! Você configurou a caixa de ferramentas do MCP para bancos de dados e 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