# elastic/mcp-server-elasticsearch architecture

> Architecture diagram of the GitHub repository elastic/mcp-server-elasticsearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elastic/mcp-server-elasticsearch
- Repository: https://github.com/elastic/mcp-server-elasticsearch

## Overview

This is a Rust MCP server that lets AI clients access Elasticsearch through stdio or streamable HTTP. The workflow is: select a transport, load configuration and expand environment variables, construct the Elasticsearch-backed MCP service, then handle tool requests against the cluster. The sampled tools cover index listing, mappings, search, ES|QL, and shard inspection; configuration also supports custom search-template/ES|QL tools and prompts. Some implementation details are unsampled, so those capabilities are shown without speculative internal call edges.

Main entry points: [`src/servers/elasticsearch/mod.rs`](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs) (Elasticsearch MCP service), [`src/lib.rs`](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs) (Server runtime), [`src/protocol/http.rs`](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/protocol/http.rs) (HTTP serving), [`src/servers/elasticsearch/base_tools.rs`](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs) (Index and mapping tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_cli["CLI commands<br/>[cli.rs]"]
  node_runtime_entry["Server runtime<br/>[lib.rs]"]
  node_config["Config parsing<br/>[lib.rs]"]
end

subgraph group_transport["MCP transports"]
  node_stdio["stdio serving<br/>[lib.rs]"]
  node_http["HTTP serving<br/>[http.rs]"]
end

subgraph group_elasticsearch["Elasticsearch capabilities"]
  node_es_service["Elasticsearch MCP service<br/>[mod.rs]"]
  node_client_provider["Request-aware ES client<br/>[mod.rs]"]
  node_index_tools["Index and mapping tools<br/>[base_tools.rs]"]
  node_search_tools["Search and ES&#124;QL<br/>[base_tools.rs]"]
  node_shard_tools["Shard inspection<br/>[base_tools.rs]"]
  node_custom_tools["Template tools<br/>[mod.rs]"]
  node_prompts["Configured prompts<br/>[mod.rs]"]
end

subgraph group_support["Shared support"]
  node_server_provider["Service provider<br/>[rmcp_ext.rs]"]
  node_interpolator["Environment interpolation<br/>[interpolator.rs]"]
  node_tool_filter["Tool inclusion filters<br/>[mod.rs]"]
end

node_client(("MCP client"))
node_cluster[("Elasticsearch cluster")]

node_client -->|"connects via stdio"| node_stdio
node_client -->|"connects via HTTP"| node_http
node_cli -->|"selects command"| node_runtime_entry
node_runtime_entry -->|"loads configuration"| node_config
node_config -->|"expands variables"| node_interpolator
node_config -->|"constructs service"| node_es_service
node_runtime_entry -->|"serves stdio"| node_stdio
node_runtime_entry -->|"starts HTTP"| node_http
node_http -->|"wraps provider"| node_server_provider
node_es_service -->|"provides client"| node_client_provider
node_es_service -->|"registers tools"| node_index_tools
node_es_service -->|"registers tools"| node_search_tools
node_client_provider -->|"sends requests"| node_cluster
node_index_tools -->|"queries indices"| node_cluster
node_search_tools -->|"runs queries"| node_cluster
node_shard_tools -->|"reads shard status"| node_cluster
node_custom_tools -.->|"runs templates"| node_cluster
node_es_service -.->|"configures tools"| node_custom_tools
node_es_service -.->|"configures prompts"| node_prompts
node_tool_filter -.->|"filters tools"| node_index_tools

click node_cli "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/cli.rs"
click node_runtime_entry "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs"
click node_config "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs"
click node_stdio "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs"
click node_http "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/protocol/http.rs"
click node_server_provider "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/utils/rmcp_ext.rs"
click node_es_service "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs"
click node_client_provider "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs"
click node_index_tools "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs"
click node_search_tools "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs"
click node_shard_tools "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs"
click node_custom_tools "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs"
click node_prompts "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs"
click node_interpolator "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/utils/interpolator.rs"
click node_tool_filter "https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runtime_entry,node_config,node_client toneBlue
class node_stdio,node_http,node_cluster toneAmber
class node_es_service,node_client_provider,node_index_tools,node_search_tools,node_shard_tools,node_custom_tools,node_prompts toneMint
class node_server_provider,node_interpolator,node_tool_filter toneRose
```

## Components

### Runtime and configuration

- [CLI commands](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/cli.rs): `src/cli.rs`
- [Server runtime](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs): `src/lib.rs`
- [Config parsing](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs): `src/lib.rs`

### MCP transports

- [stdio serving](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/lib.rs): `src/lib.rs`
- [HTTP serving](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/protocol/http.rs): `src/protocol/http.rs`

### Elasticsearch capabilities

- [Elasticsearch MCP service](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs): `src/servers/elasticsearch/mod.rs`
- [Request-aware ES client](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs): `src/servers/elasticsearch/mod.rs`
- [Index and mapping tools](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs): `src/servers/elasticsearch/base_tools.rs`
- [Search and ES|QL](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs): `src/servers/elasticsearch/base_tools.rs`
- [Shard inspection](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/base_tools.rs): `src/servers/elasticsearch/base_tools.rs`
- [Template tools](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs): `src/servers/elasticsearch/mod.rs`
- [Configured prompts](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/elasticsearch/mod.rs): `src/servers/elasticsearch/mod.rs`

### Shared support

- [Service provider](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/utils/rmcp_ext.rs): `src/utils/rmcp_ext.rs`
- [Environment interpolation](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/utils/interpolator.rs): `src/utils/interpolator.rs`
- [Tool inclusion filters](https://github.com/elastic/mcp-server-elasticsearch/blob/main/src/servers/mod.rs): `src/servers/mod.rs`

### Other components

- **MCP client**
- **Elasticsearch cluster**

## Connections

- MCP client → stdio serving: connects via stdio (evidence: `README.md`)
- MCP client → HTTP serving: connects via HTTP (evidence: `README.md`)
- CLI commands → Server runtime: selects command (evidence: `src/lib.rs`)
- Server runtime → Config parsing: loads configuration (evidence: `src/lib.rs`)
- Config parsing → Environment interpolation: expands variables (evidence: `src/lib.rs`)
- Config parsing → Elasticsearch MCP service: constructs service (evidence: `src/lib.rs`)
- Server runtime → stdio serving: serves stdio (evidence: `src/lib.rs`)
- Server runtime → HTTP serving: starts HTTP (evidence: `src/lib.rs`)
- HTTP serving → Service provider: wraps provider (evidence: `src/protocol/http.rs`)
- Elasticsearch MCP service → Request-aware ES client: provides client (evidence: `src/servers/elasticsearch/mod.rs`)
- Elasticsearch MCP service → Index and mapping tools: registers tools (evidence: `src/servers/elasticsearch/mod.rs`)
- Elasticsearch MCP service → Search and ES|QL: registers tools (evidence: `src/servers/elasticsearch/mod.rs`)
- Request-aware ES client → Elasticsearch cluster: sends requests
- Index and mapping tools → Elasticsearch cluster: queries indices (evidence: `src/servers/elasticsearch/base_tools.rs`)
- Search and ES|QL → Elasticsearch cluster: runs queries (evidence: `src/servers/elasticsearch/base_tools.rs`)
- Shard inspection → Elasticsearch cluster: reads shard status (evidence: `src/servers/elasticsearch/base_tools.rs`)
- Template tools → Elasticsearch cluster: runs templates
- Elasticsearch MCP service → Template tools: configures tools (evidence: `src/servers/elasticsearch/mod.rs`)
- Elasticsearch MCP service → Configured prompts: configures prompts (evidence: `src/servers/elasticsearch/mod.rs`)
- Tool inclusion filters → Index and mapping tools: filters tools