Recientemente, contribuimos al proyecto de mastra-ai/mastra open source agregando soporte para Elasticsearch como base de datos vectorial. Con esta nueva característica, puedes usar Elasticsearch de forma nativa en Mastra para almacenar incrustaciones. Además de los vectores, Elasticsearch ofrece un conjunto de funciones avanzadas para satisfacer todas tus necesidades de ingeniería de contexto (por ejemplo, búsqueda híbrida y reordenamiento).

En este artículo, se detalla la creación de un agente para implementar una arquitectura de Retrieval-Augmented Generation (RAG) con Elasticsearch. Te mostraremos un proyecto de demostración en el que se utiliza un enfoque agéntico para interactuar con un corpus de datos de películas de ciencia ficción almacenados en Elasticsearch. El proyecto está disponible en elastic/mastra-elasticsearch-example.

Mastra

Mastra es un marco de trabajo de TypeScript para crear aplicaciones de IA agéntica.

Una estructura de proyecto en Mastra se ve así:

En Mastra, puedes crear agentes, herramientas, flujos de trabajo y puntajes.

Un agente es una clase que acepta un mensaje como entrada y produce una respuesta como salida. Un agente puede usar herramientas, modelos de lenguaje a gran escala (LLM) y una memoria (figura 1).

Las herramientas de un agente le permiten interactuar con el "mundo externo", como comunicarse con una API web o hacer una operación interna, como consultar Elasticsearch. El componente de memoria es crucial para almacenar el historial de conversaciones, incluidas las entradas y salidas pasadas. Este contexto almacenado permite que el agente proporcione respuestas más informadas y relevantes a preguntas futuras mediante el uso de sus interacciones pasadas.

Los flujos de trabajo te permiten definir secuencias complejas de tareas mediante pasos claros y estructurados, en lugar de depender del razonamiento de un solo agente (figura 2). Te brindan control total sobre cómo se desglosan las tareas, cómo se mueven los datos entre ellas y qué se ejecuta y cuándo. Los flujos de trabajo se ejecutan con el motor de ejecución integrado de forma predeterminada o se pueden desplegar en ejecutores de flujos de trabajo.

En Mastra, también puedes definir puntuaciones, que son pruebas automatizadas que evalúan las salidas de los agentes mediante métodos calificados por modelos, basados en reglas y estadísticos. Los evaluadores devuelven puntuaciones: valores numéricos (normalmente entre 0 y 1) que cuantifican qué tan bien una salida cumple con tus criterios de evaluación. Estas puntuaciones te permiten hacer un seguimiento objetivo del rendimiento, comparar diferentes enfoques e identificar áreas de mejora en tus sistemas de IA. Los evaluadores pueden personalizarse con tus propias solicitudes y funciones de puntuación.

Elasticsearch

Para ejecutar el proyecto de demostración, necesitamos tener una instancia de Elasticsearch en ejecución. Puedes activar una prueba gratis en Elastic Cloud o instalarlo localmente usando el script start-local:

Se instalarán Elasticsearch y Kibana en tu computadora y se generará una clave API que se utilizará para configurar la integración de Mastra.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env en la carpeta elastic-start-local.

Instalar y configurar la demo

Creamos un repositorio elastic/mastra-elasticsearch-example que contiene el código fuente del proyecto de demostración. El ejemplo reportado en el repositorio ilustra cómo crear un agente en Mastra que implemente una arquitectura RAG para recuperar documentos de Elasticsearch.

Proporcionamos un set de datos para la demostración sobre películas de ciencia ficción. Extrajimos 500 películas de los sets de datos de IMDb en Kaggle.

El primer paso es instalar las dependencias del proyecto con npm, usando el siguiente comando:

Luego tenemos que configurar el archivo .env que contendrá la configuración. Podemos generar este archivo copiando la estructura del archivo .env.example , usando el siguiente comando:

Ahora podemos editar el archivo .env, agregando la información faltante:

El nombre del índice de Elasticsearch es scifi-movies. Si quieres, puedes cambiarlo usando la variable de entorno ELASTICSEARCH_INDEX_NAME.

Usamos OpenAI como servicio de incrustación, lo que significa que necesitas proporcionar una clave API para OpenAI en la variable OPENAI_API_KEY .env.

El modelo de incrustación empleado en el ejemplo es openai/text-embedding-3-small, con una dimensión de incrustación de 1536.

Para generar la respuesta final, empleamos el modelo openai/gpt-5-nano para reducir costos.

La arquitectura RAG te permite usar un modelo LLM final menos potente (y generalmente menos costoso) porque el trabajo pesado de fundamentar la respuesta está a cargo del componente de recuperación (Elasticsearch en este caso).

El LLM más pequeño solo se encarga de dos tareas principales:

• Reformulación/incrustación de la consulta: Convertir la pregunta en lenguaje natural del usuario en una incrustación de vectores para la búsqueda semántica.

• Sintetizar la respuesta: Se toman los fragmentos de contexto muy relevantes y recuperados (documentos/películas) y se los sintetiza en una respuesta coherente, final y legible por seres humanos, siguiendo las instrucciones del prompt proporcionado.

Dado que el proceso RAG proporciona el contexto fáctico exacto necesario para la respuesta, el LLM final no necesita ser masivo o muy complejo y no necesita poseer todo el conocimiento requerido dentro de sus propios parámetros (que es donde sobresalen los modelos grandes y caros). Esencialmente actúa como un sofisticado resumidor y formateador de texto para el contexto proporcionado por Elasticsearch, en lugar de ser una base de conocimientos completa en sí mismo. Esto permite el uso de modelos como gpt-5-nano para optimizar costos y latencia.

Después de la configuración del archivo .env, puedes ingestar las películas a Elasticsearch usando el siguiente comando:

Deberías ver una salida como la siguiente:

El mapping del índice de películas de ciencia ficción contiene los siguientes campos:

• incrustación, dense_vector con 1536 dimensiones, similitud del coseno.

• descripción, texto que contiene la descripción de la película.

• director, texto que contiene el nombre del director.

• título, texto que contiene el título de la película.

Generamos las incrustaciones usando el título + la descripción. Como el título y la descripción son dos campos separados, la concatenación de ambos asegura que el vector de incrustación resultante capture tanto la identidad única y específica (título) como el contexto rico y descriptivo (descripción) de la película, lo que lleva a resultados de búsqueda semántica más precisos y completos. Esta entrada combinada le brinda al modelo de incrustación una mejor representación del contenido del documento para la búsqueda por similitud.

Ejecuta la demostración

Puedes ejecutar la demo con el siguiente comando:

Este comando iniciará una aplicación web en localhost:4111 para acceder a Mastra Studio (figura 3).

Mastra Studio ofrece una UI interactiva para crear y probar tus agentes, junto con una API REST que expone tu aplicación Mastra como un servicio local. Esto te permite comenzar a construir de inmediato sin preocuparte por la integración.

Proporcionamos un Agente Elasticsearch que emplea createVectorQueryTool de Mastra como herramienta para ejecutar búsqueda semántica usando Elasticsearch. Este agente emplea el enfoque RAG para buscar documentos relevantes (es decir, películas) que respondan a la pregunta del usuario.

Este agente usa el siguiente prompt:

Si haces clic en el menú Mastra Studio > Agents y seleccionas Agente de Elasticsearch, puedes probar el agente usando un sistema de chat. Por ejemplo, puedes pedir información sobre películas de ciencia ficción con una pregunta como esta:

Encuentra 5 películas o series de TV sobre ovnis.

Notarás que el agente ejecutará el vectorQueryTool. Puedes hacer clic en la herramienta invocada para ver la entrada y la salida. Al final de la ejecución, el LLM responderá tu pregunta, dado el contexto que proviene del índice de películas de ciencia ficción de Elasticsearch (figura 4).

Mastra ejecuta los siguientes pasos internamente:

1. Conversión en vectores: La pregunta del usuario, Encuentra 5 películas o series de televisión sobre ovnis, se convierte en una incrustación de vectores mediante el modelo openai/text-embedding-3-small de OpenAI.

2. Búsqueda de vectores: Esta incrustación se usa luego para hacer una búsqueda en Elasticsearch mediante una búsqueda de vectores.

3. Recuperación de resultados: Elasticsearch devuelve una serie de 10 películas muy relevantes para la consulta (es decir, aquellas con vectores más cercanos al vector de consulta del usuario).

4. Generación de respuestas: Las películas recuperadas y la pregunta original del usuario se envían al LLM, específicamente openai/gpt-5-nano. El LLM procesa esta información y genera una respuesta final, asegurando que se cumpla la solicitud del usuario para cinco resultados.

El agente de Elasticsearch

Aquí presentamos el código fuente del agente de Elasticsearch.

El vectorQueryTool es la herramienta que se invoca para implementar la parte de recuperación del ejemplo de RAG. Emplea la implementación de ElasticSearchVector que Elastic aportó a Mastra.

El agente es un objeto de la clase agente que utiliza la herramienta vectorQueryTool, el prompt y una memoria. Como puedes ver, el código que necesitamos implementar para conectar Elasticsearch a un agente es muy sencillo.

Conclusión

En este artículo, se demostró la simplicidad y el poder de integrar Elasticsearch con el marco de trabajo Mastra para construir sofisticadas aplicaciones de IA agéntica. En concreto, te mostramos cómo crear un agente RAG capaz de efectuar búsquedas semánticas sobre un corpus de datos de películas de ciencia ficción indexados en Elasticsearch.

Una de las principales conclusiones es la contribución directa de Elastic al proyecto de código abierto Mastra, que ofrece compatibilidad nativa con Elasticsearch como almacén de vectores. Esta integración reduce considerablemente las barreras de acceso, como se puede ver en el código fuente del agente de Elasticsearch. Usando el ElasticSearchVector y createVectorQueryTool, la configuración completa para conectar Elasticsearch a tu agente requiere solo un número mínimo de líneas de código de configuración.

Elasticsearch ofrece varias características avanzadas para mejorar la relevancia de los resultados. Por ejemplo, la búsqueda híbrida aumenta significativamente la precisión combinando la búsqueda léxica con la búsqueda de vectores. Otra característica interesante es la reclasificación con los últimos modelos de Jina, que puede aplicarse al final de la búsqueda híbrida. Para obtener más información sobre estas técnicas, consulta los siguientes artículos de Elasticsearch Labs:

• Búsqueda híbrida Elasticsearch de Valentin Crettaz

• Introducción a los modelos de Jina, su funcionalidad y usos en Elasticsearch de Scott Martens

También te animamos a consultar el ejemplo proporcionado y comenzar a crear tus propios agentes basados en datos con Mastra y Elasticsearch. Para más información sobre Mastra, puedes consultar la documentación oficial aquí.

La extensión está disponible como proyecto de open source aquí.

¿Qué es Gemini CLI y cómo lo instalas?

Gemini CLI es un agente open source de IA que lleva los modelos Gemini de Google directamente a la línea de comando. Permite a los desarrolladores interactuar con la IA desde la terminal para hacer tareas como generar código, editar archivos, ejecutar comandos de shell y obtener información de la web.

A diferencia de las interfaces de chat típicas, Gemini CLI se integra con tu entorno local de desarrollo, lo que significa que puede entender el contexto del proyecto, modificar archivos, ejecutar compilaciones o pruebas, y automatizar flujos de trabajo directamente dentro de la terminal. Esto lo hace útil para desarrolladores, ingenieros de confiabilidad del sitio (SRE) e ingenieros que buscan codificación y automatización asistidas por IA sin salir de su flujo de trabajo de línea de comandos.

Gemini CLI puede instalarse usando diversos gestores de paquetes. El método más común es a través de npm:

Si quieres conocer opciones de instalación alternativas, consulta la página de instalación oficial.

Luego de la instalación, inicia la CLI ejecutando:

Verás una pantalla, como se muestra en la Figura 1:

Configurar Elasticsearch

Es necesario tener una instancia de Elasticsearch en funcionamiento. Si quieres usar el servidor Model Context Protocol (MCP), también necesitas instalar Kibana 9.3+. Para emplear la habilidad del lenguaje de búsqueda Elasticsearch (ES|QL) (esql) descrito más abajo, Kibana no es obligatorio.

Puedes activar una prueba gratis en Elastic Cloud o instalarlo localmente usando el script start-local:

Se instalarán Elasticsearch y Kibana en tu computadora y se generará una clave API que se utilizará para configurar Gemini CLI.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env en la carpeta elastic-start-local.

Si usas Elasticsearch local (por ejemplo, usar start-local), y quieres usar Elastic Agent Builder con MCP, también necesitas conectar un modelo de lenguaje grande (LLM). Puedes leer esta página de documentación para entender las diferentes opciones.

Si usas Elastic Cloud (o sin servidor), ya tienes una conexión con el LLM preconstruida.

Instala la extensión de Elasticsearch

Puedes instalar la extensión de Elasticsearch para Gemini CLI con el siguiente comando:

Puedes verificar que las extensiones se hayan instalado correctamente abriendo Gemini y ejecutando el siguiente comando:

Deberías ver la extensión de Elasticsearch disponible.

Si quieres usar la integración de MCP, necesitas tener instalada una versión de Elasticsearch 9.3 o superior. Necesitas la URL de tu servidor MCP de Kibana:

• Obtén la URL del servidor MCP desde Agentes > Ver todas las herramientas > Administrar MCP > Copiar URL del servidor MCP.

• La URL tendrá este formato: https://your-kibana-instance/api/agent_builder/mcp

Necesitas la URL del endpoint de Elasticsearch. Esta generalmente se informa en la parte superior de la página de Kibana Elasticsearch. Si estás ejecutando Elasticsearch con start-local, ya tienes el endpoint en la clave ES_LOCAL_URLen el archivo start-local.env .

También necesitas una clave API. Si estás ejecutando Elasticsearch con start-local, ya tienes ES_LOCAL_API_KEY en el archivo start-local .env . De lo contrario, puedes crear una clave API desde la interfaz de Kibana, como se indica aquí:

• En Kibana: Stack Management > Seguridad > Claves de API > Crear clave de API.

• Sugerimos establecer solo los privilegios de lectura para la clave API, habilitando el privilegio feature_agentBuilder.read como se informa aquí.

• Copia el valor de la clave API codificada.

Configura las variables de entorno requeridas en tu shell:

Instala el set de datos de ejemplo

Puedes instalar el set de datos de pedidos de comercio electrónico disponible desde Kibana. Incluye un único índice llamado kibana_sample_data_ecommerce, que contiene información sobre 4,675 pedidos de un sitio web de comercio electrónico. Para cada pedido, tenemos la siguiente información:

• Información del cliente (nombre, identificación, fecha de nacimiento, correo electrónico y más).

• Fecha del pedido.

• ID de pedido.

• Productos (lista de todos los productos con precio, cantidad, identificación, categoría, descuento y otros detalles).

• SKU.

• Precio total (sin impuestos, con impuestos).

• Cantidad total.

• Información geográfica (ciudad, país, continente, ubicación, región).

Para instalar los datos de muestra, abre la página Integraciones en Kibana (busca "Integración" en la barra superior de búsqueda) e instala los Datos de muestra. Para más detalles, consulta la documentación aquí.

El objetivo de este artículo es mostrar lo fácil que es configurar la CLI Gemini para conectarse a Elasticsearch e interactuar con el índice kibana_sample_data_ecommerce .

Cómo usar el MCP de Elasticsearch

Puedes comprobar la conexión usando el siguiente comando en Gemini:

Deberías ver el elastic-agent-builder activado, como se muestra en la Figura 2:

Elasticsearch proporciona un conjunto predeterminado de herramientas. Ve la descripción aquí.

Con estas herramientas, puedes interactuar con Elasticsearch y hacer preguntas como:

• Give me the list of all the indexes available in Elasticsearch.

• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

Dependiendo de la pregunta, Gemini usará una o varias de las herramientas disponibles para intentar responderla.

Los comandos /elastic

En la extensión Elasticsearch para Gemini CLI, también agregamos comandos/elastic.

Si ejecutas el comando /help, verás todas las opciones /elastic disponibles (Figura 3):

Estos comandos pueden ser útiles si quieres ejecutar directamente una herramienta específica del servidor MCP elastic-agent-builder. Por ejemplo, usando el siguiente comando, puedes obtener el mapping del kibana_sample_data_ecommerce:

Estos comandos son esencialmente atajos para ejecutar herramientas específicas, en lugar de depender del modelo Gemini para determinar qué herramienta debe invocarse.

Cómo usar las habilidades de Elasticsearch

Esta extensión también incluye una habilidad de agente para ES|QL, el lenguaje de búsqueda Elasticsearch disponible en Elasticsearch. Habilidades del Agente es un formato abierto que proporciona a los agentes de codificación de IA, como Gemini CLI, instrucciones personalizadas para tareas específicas. Utilizan un concepto llamado revelación progresiva, lo que significa que solo se agrega una breve descripción de la habilidad a la indicación inicial del sistema. Cuando le pides al agente que haga una tarea, como consultar Elasticsearch, hace coincidir la solicitud con la habilidad relevante y carga dinámicamente las instrucciones detalladas. Esta es una forma eficaz de gestionar los presupuestos de tokens y, al mismo tiempo, proporcionar a la IA exactamente el contexto que necesita.

La habilidadesql está diseñada para permitir que la CLI de Gemini escriba y ejecute consultas en ES|QL directamente en tu cluster. ES|QL es un poderoso lenguaje de búsqueda con barras verticales que hace que la exploración de datos, el análisis de logs y las agregaciones sean sumamente intuitivas. Con esta habilidad activada, no necesitas buscar la sintaxis de ES|QL; simplemente puedes hacer preguntas en lenguaje natural a la CLI de Gemini sobre tus datos, y el agente se encargará del resto.

Las ejecuciones se efectúan mediante comandos curl sencillos ejecutados en una terminal. Esto es posible porque Elasticsearch ofrece un amplio conjunto de API REST que se pueden utilizar fácilmente para integrar el sistema en cualquier arquitectura.

Lo que la habilidadesql ofrece:

• Detección de índices y esquemas: El agente puede usar las herramientas integradas de la habilidad para mostrar los índices disponibles y obtener el mapping de campos. Por ejemplo, antes de escribir una consulta para el set de datos de comercio electrónico, el agente puede ejecutar una verificación de esquema en kibana_sample_data_ecommerce para comprender los campos disponibles, como taxful_total_price o category.

• Traducción perfecta al lenguaje natural: la habilidad le da al agente algo más que un simple manual de referencia; proporciona una guía específica para interpretar la intención del usuario. Cuando escribes solicitudes en lenguaje natural, como "Mostrar el tiempo de respuesta promedio agrupado por servicio", el agente utiliza la función de coincidencia de patrones integrada en la habilidad para traducir al instante tus palabras en las agregaciones, filtros y comandos en ES|QL correctos.

• Autocorrección: Si una consulta falla (por ejemplo, debido a una incompatibilidad de tipos o un error de sintaxis), la habilidad devuelve la consulta generada junto con el mensaje de error exacto de Elasticsearch, lo que permite al agente corregirla al instante y volver a intentarlo sin que tengas que intervenir.

Dado que la habilidad esql también está disponible como una herramienta en el servidor MCP elastic-agent-builder, necesitamos deshabilitar este servidor momentáneamente. Puedes usar el siguiente comando para desactivarlo:

Entonces puedes simplemente escribir un mensaje como este en tu CLI de Gemini:

El agente deberá:

• Reconoce la necesidad de la habilidad esql .

• Verifica el esquema de kibana_sample_data_ecommerce.

• Construye una consulta en ES|QL, como: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.

• Ejecutar la consulta en la API de Elasticsearch.

• Presentar la respuesta final directamente en la terminal.

Aquí, presentamos un ejemplo de respuesta de Gemini al mensaje anterior:

Es interesante ver cómo el modelo Gemini genera la respuesta final mostrando todos los pasos que sigue. Aquí, puedes ver claramente la influencia de la habilidad en el proceso de razonamiento del modelo. La primera vez que el modelo reconoce que necesita usar una habilidad o ejecutar un comando de shell, pide permiso empleando el enfoque de intervención humana.

Al manejar el trabajo pesado de descubrimiento de esquemas, generación de consultas y ejecución, la habilidad esql te permite concentrarte completamente en las respuestas en lugar de en la mecánica para obtenerlas. Obtendrás los datos que necesitas, correctamente formateados y directamente en tu terminal, todo sin escribir una sola línea de sintaxis o cambiar de contexto a otra aplicación.

Conclusión

En este artículo, presentamos la extensión Elasticsearch para Gemini CLI que lanzamos recientemente. Esta extensión te permite interactuar con tu instancia de Elasticsearch mediante Gemini y el servidor MCP de Elasticsearch que ofrece Elastic Agent Builder, disponible a partir de la versión 9.3.0, así como el comando /elastic .

Además, la extensión también incluye una habilidad esql que convierte la solicitud del usuario de lenguaje natural en una consulta en ES|QL. Esta habilidad puede resultar especialmente útil cuando no se puede usar el servidor MCP, ya que la comunicación subyacente se gestiona mediante simples comandos curl ejecutados en una terminal. Elasticsearch ofrece un amplio conjunto de API REST que se pueden integrar fácilmente en cualquier proyecto. Esto es especialmente útil cuando se desarrollan aplicaciones de AI agéntica.

Para más información sobre nuestra extensión Gemini CLI, visita el repositorio del proyecto aquí.

Recientemente contribuimos al proyecto open source Google MCP Toolbox for Databases agregando soporte para Elasticsearch como base de datos.

Con esta nueva característica, ahora puedes usar Google MCP Toolbox para conectarte a Elasticsearch y “conversar” directamente con tus datos.

Elasticsearch

Es necesario tener una instancia de Elasticsearch en funcionamiento. Puedes activar una prueba gratuita en Elastic Cloud o instalarla localmente utilizando el script start-local:

Esto instalará Elasticsearch y Kibana en tu computadora y generará una clave API que se utilizará para configurar Google MCP Toolbox.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env. en la carpeta elastic-start-local.

Instala el set de datos de ejemplo

Tras la instalación, puedes iniciar sesión en Kibana con el nombre de usuario elastic y la contraseña generada por el script start-local (almacenada en un archivo .env).

Puedes instalar el conjunto de datos de pedidos de comercio electrónico disponible desde Kibana. Incluye un único índice llamado kibana_sample_data_ecommerce que contiene información sobre 4675 pedidos de un sitio web de comercio electrónico. Para cada pedido, tenemos la siguiente información:

• Información del cliente (nombre, identificación, fecha de nacimiento, correo electrónico, etc.)

• Fecha del pedido

• ID de pedido

• Productos (lista de todos los productos con precio, cantidad, identificación, categoría, descuento, etc.)

• SKU

• Precio total (sin impuestos, con impuestos)

• Cantidad total

• Información geográfica (ciudad, país, continente, ubicación, región)

Para instalar los datos de muestra, abre la página Integraciones en Kibana (busca “Integración” en la barra superior de búsqueda) e instala los “Datos de muestra”. Para obtener más detalles, consulta la documentación aquí: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

El objetivo de este artículo es mostrar lo fácil que es configurar Google MCP Toolbox para conectarse a Elasticsearch e interactuar con el índice de kibana_sample_data_ecommerce usando lenguaje natural.

Google MCP Toolbox

Google MCP Toolbox es un servidor MCP open source diseñado para facilitar la interacción segura y eficiente de aplicaciones y agentes de IA con bases de datos. El proyecto, anteriormente conocido como el “GenAI Toolbox for Databases”, cambió su denominación después de adoptar la compatibilidad total con el Protocolo de contexto de modelo (MCP). Su propósito es eliminar el trabajo pesado que tradicionalmente se requiere al conectar agentes con bases de datos, gestionando la agrupación de conexiones, autenticación, observabilidad y otras preocupaciones operativas en segundo plano.

Esencialmente, Toolbox permite a los desarrolladores definir herramientas reutilizables de alto nivel que encapsulan las interacciones con la base de datos. Estas herramientas pueden ser invocadas por cualquier cliente compatible con MCP (como un agente de IA) sin requerir que el cliente implemente consultas SQL de bajo nivel o administre conexiones de base de datos. Este enfoque reduce drásticamente la cantidad de código repetitivo necesario para crear agentes compatibles con bases de datos, lo que permite integrar operaciones de datos avanzadas en solo unas pocas líneas de lógica de aplicación. Una vez definida una herramienta, se puede compartir entre varios agentes, marcos de trabajo o lenguajes (Figura 1).

Una de las ventajas principales de usar la Toolbox es el modelo de seguridad integrado. Los flujos de autenticación como OAuth2 y OIDC son compatibles de forma nativa, lo que permite a los desarrolladores evitar manejar o almacenar credenciales confidenciales de bases de datos en agentes. La plataforma también ofrece características de observabilidad (como métricas y rastreo) a través de OpenTelemetry, que es esencial para la depuración, la supervisión y los despliegues de producción. En conjunto, MCP Toolbox sirve como una interfaz unificada, segura y extensible para interactuar con tus datos desde cualquier sistema compatible con MCP.

Cómo instalar MCP Toolbox

Puedes instalar el servidor MCP Toolbox en Linux usando el siguiente comando:

Si quieres instalarlo en macOS o Windows, puedes seguir las instrucciones detalladas aquí.

Configura la Toolbox para Elasticsearch

Para configurar el MCP Toolbox para Elasticsearch, necesitamos crear un archivo tools.yaml, de la siguiente manera:

Debes reemplazar el valor <insert-here-api-key> por una clave API válida de Elasticsearch. Si estás ejecutando Elasticsearch localmente usando start-local, puedes encontrar la clave de API en el archivo.env generado por start-local, bajo la variable ES_LOCAL_API_KEY . Si usas Elastic Cloud, puedes generar una clave API siguiendo el procedimiento descrito aquí.

Las herramientas anteriores contienen la siguiente consulta ES|QL para Elasticsearch:

Si no estás familiarizado con ES|QL, es un lenguaje de búsqueda desarrollado por Elastic, similar a SQL, que puedes usar para buscar en uno o más índices. Puedes leer más sobre ES|QL en la documentación oficial aquí.

La búsqueda anterior busca todos los pedidos almacenados en el índice kibana_sample_data_ecommerce que contienen el nombre del cliente especificado, usando el parámetro ?name (el signo de interrogación indica un parámetro).

El nombre del cliente se define en la configuración YAML anterior empleando el texto de tipo y la descripción "El nombre del cliente".

Esta herramienta se puede usar para responder preguntas sobre los pedidos de un cliente, por ejemplo: ¿Cuántos pedidos realizó el cliente Foo en octubre de 2025?

Las descripciones de las herramientas y sus parámetros son esenciales para extraer la información relevante de la solicitud en lenguaje natural del usuario. Esta extracción se realiza utilizando la capacidad de llamada de función de un modelo de lenguaje grande (LLM). En la práctica, un LLM puede determinar qué función (herramienta) debe ejecutar para obtener la información necesaria, junto con los parámetros apropiados para esa función.

Para más información sobre las llamadas a funciones, sugerimos leer el artículo de OpenAI sobre llamadas a funciones con Elasticsearch de Ashish Tiwari.

Ejecuta el servidor de Toolbox

Puedes ejecutar la MCP Toolbox usando el archivo tools.yaml anterior con el siguiente comando:

El parámetro –ui ejecuta una aplicación sitio web en http://127.0.0.1:5000/ui (Figura 2).

Puedes seleccionar la Herramientas > pedidos-clientes e insertar un nombre de cliente en el parámetro nombre (por ejemplo, Gwen Sanders) y haz clic en el botón Ejecutar herramienta. Deberías ver una respuesta JSON como se indica en la Figura 3.

La configuración se ha completado y MCP Toolbox puede ejecutar la herramienta de pedidos de clientes para comunicarse con Elasticsearch, ejecutando la consulta ES|QL.

Usar la herramienta MCP Toolbox con Gemini CLI

Podemos usar cualquier cliente del MCP para comunicarnos con MCP Toolbox for Database. Por ejemplo, podemos usar Gemini CLI, una herramienta de línea de comandos, para usar Gemini. Puedes instalar Gemini CLI siguiendo las instrucciones indicadas aquí.

Gemini CLI ofrece una extensión preconfigurada para MCP Toolbox, disponible en gemini-cli-extensions/mcp-toolbox. Puedes instalar esta extensión ejecutando el comando siguiente:

Tras la instalación, debes ir al directorio donde almacenaste el archivo de configuración tools.yaml para MCP Toolbox y ejecutar la CLI Gemini de la siguiente manera (este paso es necesario para que la CLI Gemini se configure automáticamente con MCP Toolbox):

Deberías ver un anuncio de salida como el que se muestra en la Figura 4.

Puedes comprobar si MCP Toolbox está conectada usando el siguiente comando:

Deberías ver el mcp_toolbox con las herramientas de customer-orders listadas (Figura 5).

Si el MCP Toolbox está conectado a la CLI de Gemini, ahora podemos intentar hacer algunas preguntas, como: “Dame los pedidos del cliente Gwen Sanders”. La CLI de Gemini solicitará entonces permiso para ejecutar la herramienta de pedidos de clientes desde el servidor mcp_toolbox (ver Figura 6).

Tras la confirmación, Gemini CLI ejecutará la solicitud a MCP Toolbox, obteniendo una respuesta JSON como resultado y utilizándola para dar formato a la respuesta (Figura 7).

La respuesta de Gemini CLI será un reporte que indica que Gwen Sanders hizo solo un pedido de 2 productos, por un precio total de 132 euros.

SDK de MCP Toolbox

Google MCP Toolbox también ofrece un SDK para acceder a todas las funcionalidades desde un programa escrito en Go, Python y Javascript.

Por ejemplo, el SDK de Python está disponible en Github en la siguiente página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Es necesario crear un agente simple para conectarnos a MCP Toolbox. Debemos instalar los siguientes paquetes:

Además, crear un nuevo proyecto de agente usando los siguientes comandos:

Esto creará un nuevo directorio llamado my_agent con un archivo agent.py.

Actualiza my_agent/agent.py con el siguiente contenido para conectar con Toolbox:

Crea un archivo .env con tu clave de API de Google:

Finalmente, podemos ejecutar el agente y observar los resultados. Para ejecutar el agente, puedes ejecutar el siguiente comando:

O bien, puedes servirlo a través de una interfaz web:

En ambos casos, puedes interactuar con MCP Toolbox usando una interfaz de preguntas frecuentes. Por ejemplo, puedes hacer la pregunta anterior: Dame las órdenes de la cliente Gwen Sanders.

Para más información sobre los diferentes SDK, puedes consultar esta página de documentación.

Conclusión

En este artículo, hemos mostrado la integración de Elasticsearch con Google MCP Toolbox for Databases. Mediante un sencillo archivo de configuración YAML, podemos definir un conjunto de herramientas que traducen preguntas en lenguaje natural a consultas de Elasticsearch utilizando el lenguaje ES|QL.

Mostramos cómo interactuar con el set de datos kibana_sample_data_ecommerce, que contiene pedidos de un sitio web de comercio electrónico. Con este archivo de configuración, podemos simplemente ejecutar el servidor MCP Toolbox y conectarnos a él desde cualquier cliente MCP.

Por último, mostramos cómo utilizar la CLI de Gemini como cliente para conectarse a MCP Toolbox for Databases y consultar los datos de comercio electrónico almacenados en Elasticsearch. Ejecutamos una consulta en lenguaje natural para recuperar información sobre pedidos para un cliente específico identificado por su nombre.

A medida que el ecosistema MCP sigue creciendo, este patrón (definiciones ligeras de herramientas respaldadas por infraestructuras seguras y listas para producción) crea nuevas oportunidades para construir agentes cada vez más capaces y conscientes de los datos con un esfuerzo mínimo. Ya sea que experimentes localmente con los sets de datos de muestra de Elastic o integres capacidades de búsqueda en una aplicación más amplia, MCP Toolbox ofrece una base fiable y extensible para interactuar con tus datos de Elasticsearch usando lenguaje natural.

Para obtener más información sobre el desarrollo de aplicaciones de IA agentic, puedes leer el artículo Creación de flujos de trabajo de IA agentic con Elasticsearch de Anish Mathur y Dana Juratoni.

Para obtener más información sobre Google MCP Toolbox, puedes visitar https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

ES|QL

ES|QL es un nuevo lenguaje de consulta Elasticsearch introducido en Elasticsearch 8.11.0. Ahora mismo, está disponible en vista previa técnica. Proporciona una forma poderosa de filtrar, transformar y analizar los datos almacenados en Elasticsearch.

Emplea "tuberías" (|) para manipular y transformar datos paso a paso. Este enfoque permite a los usuarios componer un serial de operaciones, donde la salida de una operación se convierte en la entrada para la siguiente, permitiendo transformaciones y análisis complejos de datos.

Por ejemplo, la siguiente consulta devuelve los primeros 3 documentos (filas) del índice sample_data :

Caso de uso: ES|Funciones de QL en el cliente oficial de PHP

Para ilustrar el ES|Características de QL desarrolladas en el cliente oficial de PHP, almacenamos en Elasticsearch un archivo CSV de 81.828 libros (54,4 MB) incluyendo la siguiente información:

Extrajimos esta lista del conjunto de datos de Amazon Books Reviews, disponible al público.

Creamos un índice books con los siguientes mapeos de Elasticsearch:

El valor rating es la media de las reseñas de clasificación tomadas del archivo Books_rating.csv de 2,9 GB.

Aquí puedes encontrar el script PHP que usamos para importar en masa todos los libros en Elasticsearch. La operación a granel consumía 7 segundos y 28 MB de RAM usando PHP 8.2.17. Con el mapeo propuesto, el tamaño del índice en Elasticsearch es de unos 62 MB.

Mapa ES|Resultados QL a un objeto PHP o clase personalizada

Podemos ejecutar ES|Consulta QL en PHP usando el punto final esql()->query() . El resultado de esta consulta es una estructura de datos de tabla. Esto se expresa en JSON usando los campos columns y values . En el campo columns tenemos la definición de name y type .

Aquí tienes un ejemplo de ES|Consulta QL para recuperar los 10 mejores libros escritos por Stephen King ordenados por las reseñas de ranking de usuarios:

El resultado JSON de Elasticsearch es el siguiente:

En este ejemplo tenemos 6 propiedades (autor, descripción, editor, valoración, título, año) relacionadas con un libro y 10 resultados, todos libros de Stephen King.

Una lista de todos los tipos soportados en ES|Aquí se informa de QL.

El objeto de respuesta $result puede acceder como un array, una cadena o un objeto ( ver aquí para más información).

Usando la interfaz objeto, podemos acceder a los valores mediante propiedades e índices. Por ejemplo, $result->values[0][4] devuelve el título (4) del primer libro (0) en la lista, $result->values[1][3] devuelve el puntaje de rango (3) del segundo libro (1), etc. Recuerda, el índice de un array en PHP empieza desde cero.

Esta interfaz puede ser suficientemente buena para algunos casos de uso, pero la mayoría de las veces nos gustaría tener una variedad de objetos como resultado.

Para mapear el resultado en un array de objetos podemos usar la nueva función mapTo() de elasticsearch-php.

Esta función está disponible directamente en el objeto de respuesta Elasticsearch. Eso significa que puedes acceder a él de la siguiente manera:

Si tienes una clase Book personalizada, puedes mapear el resultado usándola de la siguiente manera:

Si tu clase tiene otras propiedades además de las incluidas en el ES|Resultado QL, esto también funcionará. La función mapTo() usará solo las propiedades devueltas como columnas del ES|Resultado de QL.

Puedes descargar todos los ejemplos que se mencionan en este artículo aquí.