Introdução do suporte ao Elasticsearch no Google MCP Toolbox for Databases

Experimente o Elasticsearch na prática: Mergulhe em nossos notebooks de amostra, inicie um teste gratuito na nuvem ou experimente o Elastic em sua máquina local agora mesmo.

Neste artigo, vamos explicar como usar o Google MCP Toolbox com o Elasticsearch para construir uma ferramenta simples de extração de informações de um índice do Elasticsearch.

Recentemente, contribuímos para o projeto open source Google MCP Toolbox for Databases, adicionando suporte ao Elasticsearch como banco de dados.

Com esse novo recurso, agora você pode usar o Google MCP Toolbox para se conectar ao Elasticsearch e "conversar" diretamente com seus dados.

Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Você pode ativar uma avaliação gratuita no Elastic Cloud ou instalá-lo localmente usando o script start-local:

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração do Google MCP Toolbox.

A chave API será mostrada como saída do comando anterior e armazenada em um arquivo .env na pasta elastic-start-local.

Instale o conjunto de dados de exemplo

Após a instalação, você pode fazer login no Kibana usando o nome do usuário elastic e a senha gerada pelo script start-local (armazenada em um arquivo .env).

Você pode instalar o conjunto de dados de pedidos de comércio eletrônico disponível no Kibana. Inclui um único índice chamado kibana_sample_data_ecommerce contendo informações sobre 4.675 pedidos de um website de comércio eletrônico. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail, etc.)
• Data do pedido
• ID do pedido
• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto, etc.)
• SKU
• Preço total (sem impostos, com impostos)
• Quantidade total
• Informações geográficas (cidade, país, continente, localização, região)

Para instalar os dados de exemplo, abra a página Integrações no Kibana (busque por “Integração” na barra de busca superior) e instale os “Dados de Exemplo”. Confira os detalhes na documentação aqui: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

O objetivo deste artigo é mostrar como é fácil configurar o Google MCP Toolbox para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce usando linguagem natural.

Google MCP Toolbox

O Google MCP Toolbox é um servidor MCP open source projetado para facilitar a interação de aplicações e agentes de IA com bancos de dados de forma segura e eficiente. Antes chamado de "GenAI Toolbox for Databases", o projeto foi renomeado após adotar total compatibilidade com o Protocolo de Contexto de Modelo (MCP). Seu objetivo é eliminar o trabalho pesado tradicionalmente exigido ao conectar agentes a bancos de dados, lidando com agrupamento de conexões, autenticação, observabilidade e outras preocupações operacionais nos bastidores.

Essencialmente, o Toolbox permite que desenvolvedores definam ferramentas reutilizáveis e de alto nível que encapsulam interações com bancos de dados. Essas ferramentas podem então ser invocadas por qualquer cliente que cumpra o MCP — como um agente de IA — sem exigir que o cliente implemente consultas SQL de baixo nível ou gerencie conexões de banco de dados. Essa abordagem reduz drasticamente a quantidade de código padrão necessário para construir agentes conscientes de banco de dados, tornando possível integrar operações avançadas de dados em apenas algumas linhas de lógica de aplicação. Uma vez definida uma ferramenta, ela pode ser compartilhada entre vários agentes, frameworks ou linguagens (Figura 1).

Uma grande vantagem de usar o Toolbox é o modelo de segurança integrado. Fluxos de autenticação, como OAuth2 e OIDC, são aceitos de forma nativa, permitindo que os desenvolvedores evitem manipular ou armazenar credenciais confidenciais de bancos de dados em agentes. A plataforma também fornece recursos de observabilidade, incluindo métricas e rastreamento, no OpenTelemetry, que é essencial para depuração, monitoramento e implantações de produção. No geral, o MCP Toolbox serve como uma interface unificada, segura e extensível para interagir com seus dados de qualquer sistema habilitado pelo MCP.

Como instalar o MCP Toolbox

Você pode instalar o servidor MCP Toolbox no Linux usando o seguinte comando:

Para instalá-lo no macOS ou Windows, siga as instruções detalhadas aqui.

Configure o Toolbox para Elasticsearch

Para configurar o MCP Toolbox para Elasticsearch, precisamos criar um arquivo tools.yaml , conforme segue:

Você precisa trocar o valor <insert-here-api-key> por uma chave API válida do Elasticsearch. Se você estiver rodando o Elasticsearch localmente usando o start-local, pode encontrar a chave API no arquivo .env gerado pelo start-local, sob a variável ES_LOCAL_API_KEY . Se você estiver usando o Elastic Cloud, poderá gerar uma chave de API seguindo o procedimento descrito aqui.

As ferramentas anteriores contêm a seguinte consulta ES|QL para Elasticsearch:

Se você não conhece o ES|QL, é uma linguagem de consulta desenvolvida pela Elastic, semelhante ao SQL, que pode ser usada para buscar em um ou mais índices. Saiba mais sobre ES|QL na documentação oficial aqui.

A consulta acima busca todos os pedidos armazenados no índice kibana_sample_data_ecommerce que contêm o nome do cliente especificado, usando o parâmetro ?name (o ponto de interrogação indica um parâmetro).

O nome do cliente é definido na configuração YAML anterior usando a string de tipo e a descrição "O nome do cliente".

Essa ferramenta pode ser usada para responder a perguntas sobre os pedidos de um cliente - por exemplo: Quantos pedidos o cliente Foo fez em outubro de 2025?

As descrições das ferramentas e seus parâmetros são essenciais para extrair as informações relevantes da solicitação em linguagem natural do usuário. Essa extração é realizada usando o recurso de chamada de função de um modelo de linguagem grande (LLM). Na prática, um LLM pode determinar qual função (ferramenta) precisa ser executada para obter as informações necessárias, juntamente com os parâmetros apropriados para essa função.

Para saber mais sobre chamadas de função, sugerimos o artigo Chamadas de função do OpenAI com Elasticsearch, de Ashish Tiwari.

Execute o servidor Toolbox

Você pode executar o MCP Toolbox usando o arquivo tools.yaml anterior com o seguinte comando:

O parâmetro –ui executa uma aplicação web em http://127.0.0.1:5000/ui (Figura 2).

Você pode selecionar Ferramentas > customer-orders e inserir o nome do cliente no campo Nome do parâmetro (por exemplo, Gwen Sanders) e clicar no botão Executar. Você deve ver uma resposta JSON conforme a Figura 3.

A configuração está concluída, e o MCP Toolbox pode executar a ferramenta customer-orders para se comunicar com o Elasticsearch, rodando o ES|QL.

Usando o MCP Toolbox com Gemini CLI

Podemos usar qualquer cliente MCP para nos comunicar com o MCP Toolbox for Databases. Por exemplo, podemos usar o Gemini CLI, uma ferramenta de linha de comando, para usar o Gemini. Você pode instalar o Gemini CLI seguindo as instruções descritas aqui.

Gemini CLI oferece uma extensão pré-configurada para MCP Toolbox, disponível em gemini-cli-extensions/mcp-toolbox. Você pode instalar esta extensão executando o seguinte comando:

Após a instalação, você precisa ir para o diretório em que armazenou o arquivo de configuração tools.yaml do MCP Toolbox e executar a CLI do Gemini da seguinte forma (essa etapa é necessária para que a CLI do Gemini seja configurada automaticamente com o MCP Toolbox):

Você deve ver uma saída conforme a Figura 4.

Você pode verificar se a MCP Toolbox está conectada usando o seguinte comando:

Você deve ver a mcp_toolbox com as ferramentas de pedidos de clientes listadas (Figura 5).

Se o MCP Toolbox estiver conectado à interface de comando Gemini, agora podemos tentar fazer algumas perguntas, como: "Me dê os pedidos da cliente Gwen Sanders." A CLI Gemini então solicitará permissão para executar a ferramenta de pedidos do cliente ao servidor mcp_toolbox (veja a Figura 6).

Após a confirmação, a CLI Gemini executará a solicitação para a MCP Toolbox, recebendo uma resposta JSON como resultado e usando para formatar a resposta (Figura 7).

A resposta da Gemini CLI emitirá um relatório indicando que Gewn Sanders fez apenas um pedido de 2 produtos, totalizando 132 euros.

SDKs do MCP Toolbox

O Google MCP Toolbox também oferece um SDK para acessar todas as funcionalidades de um programa escrito em Go, Python e Javascript.

Por exemplo, o Python SDK está disponível no Github na seguinte página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Precisamos criar um agente simples para conectar à MCP Toolbox. Precisamos instalar os seguintes pacotes:

E crie um novo projeto de agente usando o comando a seguir:

Isso criará um novo diretório chamado my_agent com um arquivo agent.py.

Atualize my_agent/agent.py com o seguinte conteúdo para conectar ao Toolbox:

Crie um arquivo .env com sua chave API do Google:

Por fim, podemos executar o agente e observar os resultados. Para executar o agente, você pode executar o seguinte comando:

Ou pode servi-lo por meio de uma interface web:

Em ambos os casos, você pode interagir com a MCP Toolbox usando uma interface de perguntas e respostas. Por exemplo, você pode fazer a pergunta anterior: Me dê os pedidos da cliente Gwen Sanders.

Para saber mais sobre os diferentes SDKs, consulte esta página de documentação.

Conclusão

Neste artigo, demonstramos a integração com o Elasticsearch para o Google MCP Toolbox for Databases. Usando um arquivo de configuração YAML simples, podemos definir um conjunto de ferramentas que traduzem perguntas de linguagem natural em consultas do Elasticsearch usando a linguagem ES|QL.

Mostramos como interagir com os conjuntos de dados kibana_sample_data_ecommerce, que contém pedidos de um website de e-commerce. Com esse arquivo de configuração, basta executar o servidor MCP Toolbox e conectar a ele a partir de qualquer cliente MCP.

Por fim, demonstramos como usar o Gemini CLI como cliente para conectar-se ao MCP Toolbox for Databases e consultar os dados de comércio eletrônico armazenados no Elasticsearch. Executamos uma consulta em linguagem natural para obter informações sobre pedidos de um cliente específico identificado pelo nome.

À medida que o ecossistema MCP continua crescendo, esse padrão — definições leves de ferramentas apoiadas por uma infraestrutura segura e pronta para produção — gera novas oportunidades para criar agentes cada vez mais capazes e com reconhecimento de dados com o mínimo esforço. Seja experimentando localmente com os conjuntos de dados de amostra da Elastic ou integrando capacidades de buscar em uma aplicação maior, o MCP Toolbox tem uma base confiável e extensível para interagir com os dados do Elasticsearch usando linguagem natural.

Para saber mais sobre o desenvolvimento de aplicações de IA agêntica, leia o artigo Criando fluxos de trabalho de IA agêntica com Elasticsearch, de Anish Mathur e Dana Juratoni.

Para saber mais informações sobre o Google MCP Toolbox, visite https://googleapis.github.io/genai-toolbox/getting-started/introduction/.