Elasticsearch

Conecta agentes aos dados do Elasticsearch, permitindo interação em linguagem natural com índices.

Documentação

Elasticsearch MCP Server

[!CAUTION] Este servidor MCP está obsoleto e receberá apenas atualizações críticas de segurança daqui em diante. Ele foi substituído pelo Elastic Agent Builder endpoint MCP, que está disponível no Elastic 9.2.0+ e em projetos Elasticsearch Serverless.

Use o Elasticsearch MCP Server para Agentes de IA

O Elasticsearch MCP Server conecta seus agentes de IA aos dados do Elasticsearch usando o Model Context Protocol (MCP). Ele permite interações em linguagem natural com seus índices do Elasticsearch, permitindo que os agentes consultem, analisem e recuperem dados sem APIs personalizadas.

Siga estas etapas para implantar e configurar a imagem do contêiner do Elasticsearch MCP Server a partir do AWS Marketplace.

Antes de começar

Antes de começar, verifique se você tem:

Um cluster Elasticsearch (versão 8.x ou 9.x) acessível a partir do seu ambiente AWS
Credenciais de autenticação do Elasticsearch:
- Uma API key, ou
- Um par de nome de usuário e senha
Docker instalado e em execução no seu ambiente AWS (por exemplo, em uma instância EC2 ou em um serviço de contêineres)
Um cliente MCP configurado (como Claude Desktop, Cursor, VS Code ou outra ferramenta compatível com MCP)
Conectividade de rede entre o seu ambiente de implantação e o seu cluster Elasticsearch

[!NOTE]

Estas instruções se aplicam ao Elasticsearch MCP Server 0.4.0 e posteriores. Para versões 0.3.1 e anteriores, consulte o README da v0.3.1.

Implante o Elasticsearch MCP Server

O Elasticsearch MCP Server é fornecido como uma imagem de contêiner Docker disponível no AWS Marketplace. Você pode executá-lo usando o protocolo stdio (para conexões diretas de cliente) ou o protocolo streamable-HTTP (para integrações baseadas na web).

Escolha um protocolo

O servidor oferece suporte a dois protocolos:

stdio: Comunicação direta entre o cliente MCP e o servidor. Use este quando o seu cliente for compatível com stdio e executar no mesmo ambiente.
streamable-HTTP: Protocolo baseado em HTTP recomendado para integrações web, sessões com estado e clientes simultâneos.

Observação: Server-Sent Events (SSE) está obsoleto. Use streamable-HTTP em seu lugar.

Configure o protocolo stdio

Use o protocolo stdio quando o seu cliente MCP se conectar diretamente ao processo do servidor.

Defina as variáveis de ambiente para o modo stdio

Defina as seguintes variáveis de ambiente:

ES_URL: A URL do seu cluster Elasticsearch (por exemplo, https://your-cluster.es.amazonaws.com:9200)
Para autenticação, use uma destas opções:
- API key: Defina ES_API_KEY como sua API key do Elasticsearch
- Autenticação básica: Defina ES_USERNAME e ES_PASSWORD como suas credenciais do Elasticsearch
(Opcional) ES_SSL_SKIP_VERIFY: Defina como true para ignorar a verificação de certificado SSL/TLS ao conectar ao Elasticsearch. Use apenas em ambientes de desenvolvimento ou teste.

Execute o contêiner no modo stdio

Inicie o servidor MCP no modo stdio:

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

Configure o Claude Desktop

Adicione esta configuração ao seu arquivo de configuração do 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>"
      }
    }
  }
}

Substitua <elasticsearch-cluster-url> pela URL do seu cluster Elasticsearch e <elasticsearch-API-key> pela sua API key.

Configure o protocolo streamable-HTTP

Use o protocolo streamable-HTTP para integrações baseadas na web ou quando precisar oferecer suporte a vários clientes simultâneos.

Defina as variáveis de ambiente para o modo HTTP

Defina as mesmas variáveis de ambiente do protocolo stdio:

ES_URL: A URL do seu cluster Elasticsearch
Para autenticação, use uma destas opções:
- API key: Defina ES_API_KEY como sua API key do Elasticsearch
- Autenticação básica: Defina ES_USERNAME e ES_PASSWORD como suas credenciais do Elasticsearch
(Opcional) ES_SSL_SKIP_VERIFY: Defina como true para ignorar a verificação de certificado SSL/TLS

Execute o contêiner no modo HTTP

Inicie o servidor MCP no modo HTTP:

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

O endpoint streamable-HTTP está disponível em http://<host>:8080/mcp. Um endpoint de verificação de integridade está disponível em http://<host>:8080/ping.

Configure o Claude Desktop com proxy HTTP

Se você estiver usando o Claude Desktop (edição gratuita), que só oferece suporte ao protocolo stdio, use mcp-proxy para fazer a ponte entre stdio e streamable-HTTP:

Instale o mcp-proxy:
```
uv tool install mcp-proxy
```
Para opções de instalação alternativas, consulte mcp-proxy/README.md.

Adicione esta configuração ao 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"
      ]
    }
  }
}

Substitua <home-directory>, <elasticsearch-API-key>, <mcp-server-host> e <mcp-server-port> pelos seus valores.

Verifique a conexão

Após configurar seu cliente MCP, verifique se a conexão funciona:

Inicie seu cliente MCP (por exemplo, Claude Desktop ou Cursor).
Verifique se o Elasticsearch MCP Server aparece nos seus servidores MCP disponíveis.
Teste uma consulta simples por meio da interface do seu agente para confirmar que ele pode acessar seus índices do Elasticsearch.

Se a conexão falhar, verifique:

Se a URL do seu cluster Elasticsearch está correta e acessível a partir do seu ambiente AWS
Se suas credenciais de autenticação são válidas e possuem as permissões necessárias
Se existe conectividade de rede entre o contêiner e o seu cluster Elasticsearch (verifique security groups e network ACLs)
Se o Docker está em execução e o contêiner foi iniciado com sucesso (verifique os logs do contêiner com docker logs <container-id>)

Monitore integridade e status

Monitore a integridade e o funcionamento adequado do Elasticsearch MCP Server usando estes métodos:

Verifique o status do contêiner

Verifique se o contêiner está em execução:

docker ps | grep elasticsearch-mcp-server

O contêiner deve aparecer na lista com um status de Up.

Teste o endpoint de integridade (modo HTTP)

Se você estiver usando o protocolo streamable-HTTP, teste o endpoint de verificação de integridade:

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

Uma resposta bem-sucedida retorna pong, indicando que o servidor está em execução e íntegro.

Verifique os logs do contêiner

Visualize os logs do contêiner para identificar quaisquer problemas:

docker logs <container-id>

Procure por mensagens de erro relacionadas a:

Falhas de conexão com o Elasticsearch
Erros de autenticação
Problemas de conectividade de rede

Verifique a conectividade com o Elasticsearch

Teste a conectividade com o seu cluster Elasticsearch a partir do contêiner:

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

Ou com uma API key:

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

Uma resposta bem-sucedida indica que o contêiner consegue alcançar o seu cluster Elasticsearch.

Segurança e informações confidenciais

O Elasticsearch MCP Server trata as credenciais de autenticação com segurança:

Armazenamento de credenciais

API keys e senhas: Armazenadas apenas em variáveis de ambiente passadas ao contêiner. Elas não são persistidas em disco nem registradas em logs.
Variáveis de ambiente: Defina-as ao executar o contêiner. Use o AWS Secrets Manager ou o AWS Systems Manager Parameter Store para gerenciar credenciais com segurança em ambientes de produção.

Criptografia de dados

Em trânsito: O servidor MCP se comunica com o Elasticsearch por HTTPS quando o seu ES_URL usa o protocolo https://. Garanta que o seu cluster Elasticsearch tenha SSL/TLS habilitado.
Em repouso: O contêiner não armazena dados localmente. Todos os dados permanecem no seu cluster Elasticsearch, que usa as configurações de criptografia do seu cluster.

Práticas recomendadas

Roteie API keys regularmente (a cada 30–90 dias em ambientes de produção)
Use API keys com as permissões mínimas necessárias (acesso somente leitura a índices específicos quando possível)
Nunca confirme credenciais no controle de versão nem as compartilhe em logs
Use o AWS Secrets Manager ou o Parameter Store para injetar credenciais em tempo de execução em vez de codificá-las

Cotas de serviço da AWS

O Elasticsearch MCP Server é executado como um contêiner no seu ambiente AWS. Considere estas cotas de serviço da AWS:

Limites de instância EC2: Se estiver executando no EC2, garanta que o tipo da sua instância ofereça suporte à sua carga de trabalho esperada
Elastic Container Service (ECS): Se estiver usando ECS, revise as cotas de serviço do ECS
Elastic Kubernetes Service (EKS): Se estiver usando EKS, revise as cotas de serviço do EKS
Largura de banda de rede: Garanta largura de banda de rede suficiente entre o seu contêiner e o cluster Elasticsearch

Para solicitar aumentos de cotas, use o console de Service Quotas da AWS ou consulte o Guia de Referência Geral da AWS.

Ferramentas disponíveis

Após a conexão, o servidor MCP fornece estas ferramentas ao seu agente:

list_indices: Liste todos os índices Elasticsearch disponíveis
get_mappings: Obtenha os mapeamentos de campos de um índice Elasticsearch específico
search: Realize uma pesquisa no Elasticsearch usando o query DSL
esql: Execute uma consulta ES|QL
get_shards: Obtenha informações de shards de todos ou de índices específicos

Seu agente pode usar estas ferramentas para interagir com seus dados do Elasticsearch por meio de conversas em linguagem natural.

Próximas etapas

Conheça os recursos com tecnologia de IA disponíveis na plataforma Elastic
Explore o Agent Builder para criar agentes de IA personalizados com Elasticsearch