Elasticsearch

Conecta agentes a datos de Elasticsearch, permitiendo interacción en lenguaje natural con índices.

GitHub
705
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Elasticsearch

[!CAUTION] Este servidor MCP está obsoleto y solo recibirá actualizaciones críticas de seguridad en el futuro. Ha sido reemplazado por el Elastic Agent Builder punto final MCP, que está disponible en Elastic 9.2.0+ y en proyectos Elasticsearch Serverless.

Usar el servidor MCP de Elasticsearch para agentes de IA

El servidor MCP de Elasticsearch conecta sus agentes de IA a los datos de Elasticsearch mediante el Protocolo de Contexto de Modelo (MCP). Permite interacciones en lenguaje natural con sus índices de Elasticsearch, lo que permite a los agentes consultar, analizar y recuperar datos sin APIs personalizadas.

Siga estos pasos para implementar y configurar la imagen de contenedor del servidor MCP de Elasticsearch desde AWS Marketplace.

Antes de comenzar

Antes de comenzar, asegúrese de tener:

  • Un clúster de Elasticsearch (versión 8.x o 9.x) accesible desde su entorno de AWS
  • Credenciales de autenticación de Elasticsearch:
  • Docker instalado y en ejecución en su entorno de AWS (por ejemplo, en una instancia EC2 o en un servicio de contenedores)
  • Un cliente MCP configurado (como Claude Desktop, Cursor, VS Code u otra herramienta compatible con MCP)
  • Conectividad de red entre su entorno de implementación y su clúster de Elasticsearch

[!NOTE]

Estas instrucciones se aplican al servidor MCP de Elasticsearch 0.4.0 y posteriores. Para versiones 0.3.1 y anteriores, consulte el README para v0.3.1.

Implementar el servidor MCP de Elasticsearch

El servidor MCP de Elasticsearch se proporciona como una imagen de contenedor Docker disponible en AWS Marketplace. Puede ejecutarlo utilizando el protocolo stdio (para conexiones directas de clientes) o el protocolo streamable-HTTP (para integraciones basadas en web).

Elegir un protocolo

El servidor admite dos protocolos:

  • stdio: Comunicación directa entre el cliente y el servidor MCP. Úselo cuando su cliente admita stdio y se ejecute en el mismo entorno.
  • streamable-HTTP: Protocolo basado en HTTP recomendado para integraciones web, sesiones con estado y clientes concurrentes.

Nota: Los eventos enviados por el servidor (SSE) están obsoletos. Use streamable-HTTP en su lugar.

Configurar el protocolo stdio

Use el protocolo stdio cuando su cliente MCP se conecte directamente al proceso del servidor.

Establecer variables de entorno para el modo stdio

Establezca las siguientes variables de entorno:

  • ES_URL: La URL de su clúster de Elasticsearch (por ejemplo, https://your-cluster.es.amazonaws.com:9200)
  • Para la autenticación, use una de estas opciones:
    • Clave de API: Establezca ES_API_KEY a su clave de API de Elasticsearch
    • Autenticación básica: Establezca ES_USERNAME y ES_PASSWORD a sus credenciales de Elasticsearch
  • (Opcional) ES_SSL_SKIP_VERIFY: Establezca a true para omitir la verificación de certificados SSL/TLS al conectarse a Elasticsearch. Use esto solo para entornos de desarrollo o pruebas.

Ejecutar el contenedor en modo stdio

Inicie el servidor MCP en modo stdio:

docker run -i --rm \
  -e ES_URL \
  -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch \
  stdio

Configurar Claude Desktop

Agregue esta configuración a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch",
        "stdio"
      ],
      "env": {
        "ES_URL": "<elasticsearch-cluster-url>",
        "ES_API_KEY": "<elasticsearch-API-key>"
      }
    }
  }
}

Reemplace <elasticsearch-cluster-url> con la URL de su clúster de Elasticsearch y <elasticsearch-API-key> con su clave de API.

Configurar el protocolo streamable-HTTP

Use el protocolo streamable-HTTP para integraciones basadas en web o cuando necesite admitir múltiples clientes concurrentes.

Establecer variables de entorno para el modo HTTP

Establezca las mismas variables de entorno que el protocolo stdio:

  • ES_URL: La URL de su clúster de Elasticsearch
  • Para la autenticación, use una de estas opciones:
    • Clave de API: Establezca ES_API_KEY a su clave de API de Elasticsearch
    • Autenticación básica: Establezca ES_USERNAME y ES_PASSWORD a sus credenciales de Elasticsearch
  • (Opcional) ES_SSL_SKIP_VERIFY: Establezca a true para omitir la verificación de certificados SSL/TLS

Ejecutar el contenedor en modo HTTP

Inicie el servidor MCP en modo HTTP:

docker run --rm \
  -e ES_URL \
  -e ES_API_KEY \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch \
  http

El punto final streamable-HTTP está disponible en http://<host>:8080/mcp. Un punto final de verificación de salud está disponible en http://<host>:8080/ping.

Configurar Claude Desktop con proxy HTTP

Si está usando Claude Desktop (edición gratuita) que solo admite el protocolo stdio, use mcp-proxy para conectar stdio a streamable-HTTP:

  1. Instale mcp-proxy:

    uv tool install mcp-proxy

    Para opciones de instalación alternativas, consulte mcp-proxy/README.md.

  2. Agregue esta configuración a Claude Desktop:

    {
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "/<home-directory>/.local/bin/mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "--header", "Authorization", "ApiKey <elasticsearch-API-key>",
        "http://<mcp-server-host>:<mcp-server-port>/mcp"
      ]
    }
  }
}

    Reemplace <home-directory>, <elasticsearch-API-key>, <mcp-server-host> y <mcp-server-port> con sus valores.

Verificar la conexión

Después de configurar su cliente MCP, verifique que la conexión funcione:

  1. Inicie su cliente MCP (por ejemplo, Claude Desktop o Cursor).
  2. Verifique que el servidor MCP de Elasticsearch aparezca en sus servidores MCP disponibles.
  3. Pruebe una consulta simple a través de su interfaz de agente para confirmar que puede acceder a sus índices de Elasticsearch.

Si la conexión falla, verifique:

  • Que la URL de su clúster de Elasticsearch sea correcta y accesible desde su entorno de AWS
  • Que sus credenciales de autenticación sean válidas y tengan los permisos necesarios
  • Que exista conectividad de red entre el contenedor y su clúster de Elasticsearch (verifique los grupos de seguridad y las ACL de red)
  • Que Docker esté en ejecución y el contenedor se haya iniciado correctamente (verifique los registros del contenedor con docker logs <container-id>)

Monitorear salud y estado

Monitoree la salud y el correcto funcionamiento del servidor MCP de Elasticsearch usando estos métodos:

Verificar el estado del contenedor

Verifique que el contenedor esté en ejecución:

docker ps | grep elasticsearch-mcp-server

El contenedor debería aparecer en la lista con un estado de Up.

Probar el punto final de salud (modo HTTP)

Si está usando el protocolo streamable-HTTP, pruebe el punto final de verificación de salud:

curl http://<host>:8080/ping

Una respuesta exitosa devuelve pong, lo que indica que el servidor está en ejecución y saludable.

Verificar los registros del contenedor

Vea los registros del contenedor para identificar cualquier problema:

docker logs <container-id>

Busque mensajes de error relacionados con:

  • Fallos de conexión con Elasticsearch
  • Errores de autenticación
  • Problemas de conectividad de red

Verificar la conectividad con Elasticsearch

Pruebe la conectividad a su clúster de Elasticsearch desde el contenedor:

docker exec <container-id> curl -k -u <username>:<password> <ES_URL>

O con una clave de API:

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

Una respuesta exitosa indica que el contenedor puede alcanzar su clúster de Elasticsearch.

Seguridad e información sensible

El servidor MCP de Elasticsearch maneja las credenciales de autenticación de forma segura:

Almacenamiento de credenciales

  • Claves de API y contraseñas: Se almacenan solo en variables de entorno pasadas al contenedor. No se persisten en disco ni se registran.
  • Variables de entorno: Se establecen al ejecutar el contenedor. Use AWS Secrets Manager o AWS Systems Manager Parameter Store para administrar las credenciales de forma segura en entornos de producción.

Cifrado de datos

  • En tránsito: El servidor MCP se comunica con Elasticsearch a través de HTTPS cuando su ES_URL usa el protocolo https://. Asegúrese de que su clúster de Elasticsearch tenga SSL/TLS habilitado.
  • En reposo: El contenedor no almacena datos localmente. Todos los datos permanecen en su clúster de Elasticsearch, que usa la configuración de cifrado de su clúster.

Mejores prácticas

  • Rote las claves de API regularmente (cada 30-90 días para entornos de producción)
  • Use claves de API con los permisos mínimos requeridos (acceso de solo lectura a índices específicos cuando sea posible)
  • Nunca envíe credenciales al control de versiones ni las comparta en registros
  • Use AWS Secrets Manager o Parameter Store para inyectar credenciales en tiempo de ejecución en lugar de codificarlas

Cuotas de servicio de AWS

El servidor MCP de Elasticsearch se ejecuta como un contenedor en su entorno de AWS. Considere estas cuotas de servicio de AWS:

  • Límites de instancias EC2: Si se ejecuta en EC2, asegúrese de que su tipo de instancia admita su carga de trabajo esperada
  • Elastic Container Service (ECS): Si usa ECS, revise las cuotas de servicio de ECS
  • Elastic Kubernetes Service (EKS): Si usa EKS, revise las cuotas de servicio de EKS
  • Ancho de banda de red: Asegúrese de tener suficiente ancho de banda de red entre su contenedor y el clúster de Elasticsearch

Para solicitar aumentos de cuota, use la consola de cuotas de servicio de AWS o consulte la Guía de referencia general de AWS.

Herramientas disponibles

Una vez conectado, el servidor MCP proporciona estas herramientas a su agente:

  • list_indices: Listar todos los índices de Elasticsearch disponibles
  • get_mappings: Obtener asignaciones de campos para un índice de Elasticsearch específico
  • search: Realizar una búsqueda en Elasticsearch usando query DSL
  • esql: Ejecutar una consulta ES|QL
  • get_shards: Obtener información de fragmentos para todos o índices específicos

Su agente puede usar estas herramientas para interactuar con sus datos de Elasticsearch a través de conversaciones en lenguaje natural.

Próximos pasos

  • Conozca las funciones impulsadas por IA disponibles en la plataforma Elastic
  • Explore Agent Builder para crear agentes de IA personalizados con Elasticsearch