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 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 ("Atualizações 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. Confira vários clientes do MCP e verifique se eles conseguem acessar a interface do MCP do conjunto de dados do BigQuery.

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.
• Teste a configuração do MCP Toolbox for Databases no ambiente local.

O que é necessário

• Navegador da Web Chrome.
• Um ambiente de desenvolvimento local do Python.
• Um ambiente local do Node.js com a versão 5.2.0 ou mais recente do npm.

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 Chat com o agente sobre essas notas da versão? Talvez uma consulta simples, como "Atualize as notas de lançamento do Google Cloud".

Vamos analisar o objetivo final. Esta é uma captura de tela real do meu Visual Studio Code executando o CoPilot e estou no modo agente, perguntando sobre as notas de lançamento do Google Cloud:

Vamos começar a criar isso e, no processo, aprender a expor seus conjuntos de dados do BigQuery em vários clientes do MCP.

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 usar um ambiente de desenvolvimento integrado ou qualquer outro ambiente de desenvolvimento de agentes (clientes do MCP) que se comunique com o endpoint do MCP Toolbox e nos permita enviar consultas naturais para fazer perguntas sobre nosso conjunto de dados. Pense nisso como uma ferramenta que você está configurando, 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

Assim, recebo 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 versões do seu sistema operacional e arquitetura e faça o download do binário correto.

export VERSION=0.6.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 forma 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 fonte. 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 Toolbox 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" --port 7000

O servidor da Toolbox do MCP é executado por padrão na porta 5000, mas neste caso especificamos que ele seja executado na 7000.

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

2025-04-25T16:05:45.603871+05:30 INFO "Initialized 1 sources."
2025-04-25T16:05:45.603943+05:30 INFO "Initialized 0 authServices."
2025-04-25T16:05:45.604092+05:30 INFO "Initialized 1 tools."
2025-04-25T16:05:45.604105+05:30 INFO "Initialized 2 toolsets."
2025-04-25T16:05:45.604706+05:30 INFO "Server ready to serve!"

Basta iniciar o navegador e acessar o seguinte URL:

http://127.0.0.1:7000

Isso vai gerar o seguinte resultado:

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

http://127.0.0.1:7000/api/toolset

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

O servidor MCP, conforme a documentação, agora está disponível no seguinte URL:

http://127.0.0.1:7000/mcp/sse

A saída é mostrada abaixo:

event: endpoint
data: https://<some-url-pattern>/mcp?sessionId=bf6bfb66-36fe-48a4-8340-ac68008ee873

Vamos testar nosso servidor MCP com clientes MCP na próxima seção.

9. Como testar o servidor MCP com vários clientes MCP

Vamos testar nosso servidor MCP recém-criado com alguns clientes MCP.

MCP Inspector com a caixa de ferramentas

A primeira ferramenta a ser usada é o MCP Inspector com a Toolbox. Para isso, você precisa ter o npx instalado. O Cloud Shell vai solicitar a instalação do pacote. Instale o app.

Você precisa dar o seguinte comando:

npx @modelcontextprotocol/inspector

Isso vai iniciar o servidor, e você vai ver uma saída semelhante a esta:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Acesse a página do MCP Inspector conforme mencionado. A primeira coisa que você precisa fazer é configurar esse cliente para se comunicar com o servidor do MCP.

Selecione o tipo de transporte como SSE e informe o URL, conforme mencionado anteriormente, ou seja, http://127.0.0.1:7000/mcp/sse. Clique em Connect. Se tudo correr bem, o status de conexão vai aparecer como mostrado abaixo:

No lado direito, você pode conferir a lista de ferramentas clicando em List Tools.

Em seguida, clique na ferramenta search_release_notes_bq. Como não temos parâmetros para transmitir, basta clicar no botão Run tool. Ele invoca a Toolbox, que se conecta à fonte de dados do BigQuery e recupera os dados, conforme mostrado abaixo:

VS Code no modo agente com o CoPilot

A documentação oficial tem as etapas sobre como se conectar à Toolbox para várias fontes de dados e ambientes de desenvolvimento integrado (IDEs) aqui.

Nesta seção, vamos conferir como configurar e usar servidores MCP no VS Code. Ele está disponível na versão de pré-lançamento, e a documentação oficial é completa e está disponível aqui.

Supondo que você tenha iniciado o VS Code, inicie o Command Palette e execute o seguinte comando:

Em seguida, selecione HTTP sse, já que temos o URL do SSE.

Ele vai pedir o SSE endpoint, que vamos fornecer:

Em seguida, alguns outros detalhes serão confirmados. Eu escolhi adicioná-lo às minhas configurações de usuário para abrir o arquivo settings.json, onde posso ver a configuração:

Basta clicar em Start, que aparece acima, ou usar o comando Palette.

O status muda para Running.

Agora, podemos iniciar o modo de chat do CoPilot e, no modo Agent, fornecer #search_release_notes_bq para indicar que queremos usar essa ferramenta e um exemplo de texto de consulta, conforme mostrado abaixo:

10. Parabéns

Parabéns! Você configurou a Toolbox 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