elastic-mcp is a Model Context Protocol (MCP) server for Elasticsearch, offering read-only access by default with optional write operations.
Search & Data Retrieval
search — Execute full Query DSL searches with queries, aggregations, sorting, pagination, and source filtering
count — Count documents matching an optional query
get_document — Fetch a single document by index and ID
esql — Run ES|QL queries with column metadata and keyed row objects (requires Elasticsearch 8.11+)
Index Inspection
list_indices — List indices with health, status, doc count, and size (falls back to names-only if monitor privilege is missing)
get_mapping — Retrieve field mappings (falls back to _field_caps if view_index_metadata is missing)
get_settings — Get settings for one or more indices
get_aliases — List index aliases, optionally filtered by name
list_shards — List shards with role, state, doc count, store size, and node info
Cluster Monitoring
cluster_health — Get cluster health, optionally scoped to specific indices
cluster_stats — Get cluster-wide statistics (indices, nodes, shards, resource usage)
cluster_info — Get basic cluster info (name, UUID, version)
list_nodes — List nodes with role, heap, CPU, and load info
Kibana Integration
get_kibana_object — Fetch a Kibana saved object (dashboard, visualization, lens, index-pattern, etc.) by <type>:<id>, with inline JSON decoding and reference resolution
Optional Write Operations (enabled via ELASTICSEARCH_ENABLE_WRITES=true)
Index, update, or delete documents
Create or delete indices
Notable Characteristics
Read-only by default, making it safe out of the box
Supports Elasticsearch 8.x and 9.x with automatic version detection (or manual pinning)
Works with deployments behind a reverse proxy with a base path
Degrades gracefully when certain privileges (e.g., monitor, view_index_metadata) are missing
Supports API key and basic auth, with optional CA fingerprint and TLS verification control
Provides read-only tools for searching, counting, retrieving documents, listing indices, getting mappings, settings, aliases, shard info, cluster health, stats, node info, and Kibana saved objects; optional write tools for indexing, updating, deleting documents, and managing indices. Supports Elasticsearch 8.x and 9.x, base paths, and API key authentication.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@elastic-mcp search the orders index for pending shipments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚠️ Disclaimer: this MCP server was vibe coded. It was built iteratively with an AI assistant and is typechecked and unit-tested, but review it yourself before relying on it — especially the write tools — and use it at your own risk.
A Model Context Protocol server for Elasticsearch, written in JavaScript with JSDoc types checked by TypeScript (@ts-check / checkJs). Read-only by default, with optional write tools.
It exposes search, index inspection, and cluster information tools over the stdio transport, and transparently supports:
Elasticsearch deployments served behind a reverse proxy under a base path (for example https://host/elasticsearch) — something the official client does not handle out of the box.
Both Elasticsearch 8.x and 9.x clusters — the v9 client speaks compatible-with=9 and is rejected by 8.x clusters, so the matching client major is selected at startup (auto-detected or pinned).
Tested in corporate environments where API keys are often issued to restricted users with limited privileges (e.g. index
readonly, without clustermonitororview_index_metadata). The server is built to degrade gracefully in these setups rather than fail outright — it falls back to lower-privilege APIs where possible and surfaces clear authorization errors otherwise. See Elasticsearch version compatibility and the privilege fallback table for details.
Run it straight from npm with npx (no install needed — set the environment variables from
Configuration first):
ELASTICSEARCH_URL=http://localhost:9200/elastic npx elastic-mcpOr install it globally to get the elastic-mcp command on your PATH:
npm install -g elastic-mcp
ELASTICSEARCH_URL=http://localhost:9200/elastic elastic-mcpAdd the server to your MCP client configuration:
{
"mcpServers": {
"elastic": {
"command": "npx",
"args": ["-y", "elastic-mcp"],
"env": {
"ELASTICSEARCH_URL": "https://host/elasticsearch",
"ELASTICSEARCH_API_KEY": "<base64-api-key>"
}
}
}
}Related MCP server: Elasticsearch MCP Server
Always registered, and all marked read-only (readOnlyHint).
Tool | Description |
| Run a Query DSL search (query, aggs, sort, size, from, _source). |
| Count documents matching an optional query. |
| Run an ES|QL query (complete query string); returns column metadata plus keyed row objects. Requires Elasticsearch 8.11+. |
| Fetch a single document by index and id. |
| List indices with health, status, doc count, and size; falls back to names-only via |
| Get field mappings for one or more indices; falls back to read-level |
| Get settings for one or more indices. |
| List index aliases. |
| List shards with role, state, doc count, store size, and node (equivalent to |
| Fetch a Kibana saved object by |
| Cluster health, optionally scoped to indices. |
| Cluster-wide statistics. |
| Cluster name, UUID, and version. |
| List nodes with role, heap, CPU, and load. |
Off by default. Registered only when ELASTICSEARCH_ENABLE_WRITES=true. Each is marked
destructiveHint (except create_index) so MCP clients can prompt for confirmation, and of course only
works if the API key carries the matching write privileges.
Tool | Description |
| Create or replace a document (auto-generates an id if omitted; |
| Partially update a document by id, with optional upsert. |
| Delete a single document by id. |
| Create an index, optionally with mappings, settings, and aliases. |
| Permanently delete one or more indices — cannot be undone. |
Configuration is read from environment variables (see .env.example):
Variable | Required | Description |
| yes | Endpoint URL, optionally including a base path. |
| no | Base64 API key; takes precedence over basic auth. |
| no | Basic-auth username. |
| no | Basic-auth password. |
| no | SHA-256 fingerprint of the CA certificate. |
| no | Defaults to |
| no |
|
| no | Set to |
The official client always sends a compatible-with=<major> media type that matches its own major
version, and a cluster of a different major rejects it. To work against both 8.x and 9.x clusters, both
client majors are bundled and the right one is chosen at startup:
auto (default) — probe the cluster's root endpoint (with a plain application/json request that
side-steps the compatibility header) and pick the matching client major. Anything up to 8.x uses the v8
client; 9.x and newer use the v9 client.
8 / 9 — pin the client major explicitly and skip the probe.
Note: the root probe requires the
cluster:monitor/mainprivilege. Index-scoped API keys often lack it (it can only be granted by an admin), in which case the probe fails withaction [cluster:monitor/main] is unauthorized. When that happens the server logs a warning and falls back to the v8 client, which speakscompatible-with=8— accepted by both 8.x and 9.x clusters — so search and index inspection keep working. SetELASTICSEARCH_API_VERSIONexplicitly to skip the probe (and the warning) entirely.
When ELASTICSEARCH_URL contains a path (e.g. https://host/elasticsearch), the URL is split into its
origin (https://host) and prefix (/elasticsearch). A custom connection class prepends the prefix to every
request path, because the official client routes requests against the origin only and silently drops the path.
By default the server is read-only, so it only needs cluster monitor rights (for cluster_health,
cluster_stats, cluster_info, list_nodes, and the _cat listings) plus read and
view_index_metadata on the indices you want to expose. Create a least-privilege key with the
Create API key API:
POST /_security/api_key
{
"name": "elastic-mcp",
"role_descriptors": {
"elastic_mcp_read_only": {
"cluster": ["monitor"],
"indices": [
{
"names": ["*"],
"privileges": ["read", "view_index_metadata"]
}
]
}
}
}Or with curl:
curl -u elastic -X POST "$ELASTICSEARCH_URL/_security/api_key" \
-H 'Content-Type: application/json' \
-d '{
"name": "elastic-mcp",
"role_descriptors": {
"elastic_mcp_read_only": {
"cluster": ["monitor"],
"indices": [
{ "names": ["*"], "privileges": ["read", "view_index_metadata"] }
]
}
}
}'The response contains an encoded field — that base64 value is exactly what ELASTICSEARCH_API_KEY expects:
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "elastic-mcp",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}ELASTICSEARCH_API_KEY=VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==Restrict indices[].names to specific index names or patterns to narrow access further.
get_kibana_object)get_kibana_object reads Kibana's saved objects straight from the .kibana_analytics and .kibana
indices. These are restricted system indices, so a plain read on * does not reach them — the role
needs a dedicated entry that opts in with allow_restricted_indices. Add it alongside the existing read
entry (keep the wildcard entry at false so the key cannot read other system indices such as .security-*):
{
"name": "elastic-mcp",
"role_descriptors": {
"elastic_mcp_read_only": {
"cluster": ["monitor"],
"indices": [
{ "names": ["*"], "privileges": ["read", "view_index_metadata"], "allow_restricted_indices": false },
{ "names": [".kibana*"], "privileges": ["read"], "allow_restricted_indices": true }
]
}
}
}To widen an existing key without rotating it, the Update API key API
(PUT /_security/api_key/<id>) rewrites its role_descriptors in place — the id and encoded value are
unchanged, so ELASTICSEARCH_API_KEY does not need updating. Omit this entry entirely if you do not use
get_kibana_object; the tool then returns an authorization error and the rest of the server is unaffected.
ELASTICSEARCH_ENABLE_WRITES=true)The read-only key above cannot mutate data — the write tools would return authorization errors. To allow
them, add the relevant index privileges: write (covers index_document, update_document,
delete_document), create_index, and delete_index:
{
"name": "elastic-mcp",
"role_descriptors": {
"elastic_mcp_read_write": {
"cluster": ["monitor"],
"indices": [
{
"names": ["*"],
"privileges": ["read", "view_index_metadata", "write", "create_index", "delete_index"]
}
]
}
}
}Grant only the subset you need — for example drop delete_index if you never delete indices. Cluster
monitor remains optional (see the fallback table below).
Some tools degrade gracefully when privileges are missing, falling back once to a lower-privilege API and remembering that for the rest of the process so they don't retry the rejected endpoint:
Tool | Needs | Fallback when missing | Granted by |
| cluster |
|
|
|
|
|
|
So a key with only read + view_index_metadata (or even just read) still gets useful results from
search, count, esql, get_document, get_mapping, and list_indices. The tools that have no lower-privilege
equivalent — cluster_health, cluster_stats, cluster_info, list_nodes (cluster monitor),
get_settings, get_aliases (view_index_metadata), and get_kibana_object (restricted .kibana* read,
see above) — return an authorization error without the privilege.
See CLAUDE.md for the project layout, architecture notes, and coding conventions.
ISC — see LICENSE.
Get the health of the cluster, optionally scoped to specific indices.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional index name or pattern to scope the health report | |
| waitForStatus | No | Wait until the cluster reaches at least this status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds no behavioral details beyond what the schema provides (e.g., optional scoping). It does not disclose any traits like return format or latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the main action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 optional params, no output schema), the description is nearly complete. However, it could mention the status levels returned or common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. The description adds no extra meaning; it merely restates the index parameter optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves cluster health, optionally scoped to indices. The verb 'Get' and resource 'health' are specific, but it does not distinguish itself from sibling tools like cluster_info or cluster_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention when to use it instead of cluster_info, cluster_stats, or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get basic cluster information: name, UUID, and Elasticsearch version (the root endpoint).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, indicating safe read-only behavior. The description adds value by specifying the exact fields returned (name, UUID, version), which goes beyond the annotation and clarifies the tool's output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose. Every word adds value, with no redundancy or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is complete. It explicitly lists the returned information (name, UUID, version), providing sufficient context for an agent to understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, and the description does not need to explain any. Schema coverage is 100% (empty), so the description is sufficient. No additional parameter information is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving basic cluster information including name, UUID, and Elasticsearch version. It specifies the resource (cluster) and action (get), and distinguishes from sibling tools like cluster_health by noting it is the 'root endpoint'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide usage guidelines, such as when to use this tool versus alternatives. While the purpose is clear, it lacks explicit context for when not to use it or specific scenarios. However, the mention of 'basic' information implicitly guides towards simple identification tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get cluster-wide statistics covering indices, nodes, shards, and resource usage.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds context by specifying the scope of statistics (indices, nodes, shards, resource usage), going beyond the annotation's bare indication of safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the purpose efficiently with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the main behavioral aspects (what is returned). Slightly missing details on response structure, but acceptable for a stateless, read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so the description correctly avoids parameter details. Baseline 4 is appropriate as no compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get cluster-wide statistics' and lists the covered areas (indices, nodes, shards, resource usage), distinguishing it from siblings like cluster_health and cluster_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for broad statistics vs health or info, but does not explicitly state when to use this tool over alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count the documents in an index that match an optional Query DSL query.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name, comma-separated list, or pattern | |
| query | No | Query DSL query object; omit to count every document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so no behavioral disclosure needed for safety. The description adds that the tool counts documents with optional query, which is transparent. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, perfectly concise, front-loaded with verb and object. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with well-described schema and no output schema, the description is adequately complete. It could mention the return type (count number) but is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for both parameters. The description adds useful context for 'query' ('omit to count every document'), enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool counts documents in an index, optionally filtered by a Query DSL query. It distinguishes from siblings like 'search' (returns documents) and 'get_document' (specific doc).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for counting documents, but does not explicitly state when not to use it or mention alternatives like 'search' for retrieving actual documents. Guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an ES|QL (Elasticsearch Query Language) query and return the result as column metadata plus row objects. Good for filtering, STATS aggregations, and sorting expressed as a piped query string, e.g. FROM idx | WHERE status == "open" | STATS count = COUNT(*) BY host | SORT count DESC. Requires Elasticsearch 8.11+.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The complete ES|QL query string, e.g. `FROM my-index | LIMIT 10` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description confirms it runs a read query. No contradictions. Additional behavioral details are not necessary given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded with the purpose, then an example and a requirement. Every word adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, full schema coverage, and readOnlyHint annotation, the description is complete. It mentions the output format (column metadata plus row objects), so no need for an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'query' with 100% schema description coverage. The description adds value by providing an example query format and syntax, exceeding the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs an ES|QL query and returns results as column metadata plus row objects. Includes an example. Distinguishes from sibling tools like search or get_document by specifying the ES|QL query language.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an example query and a requirement (Elasticsearch 8.11+). Does not explicitly state when not to use, but the context and example give adequate guidance for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List index aliases, optionally filtered by name (equivalent to _cat/aliases). Falls back to the index-level _resolve/index API when the cluster "monitor" privilege is missing.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional alias name or pattern to filter by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by disclosing the fallback to _resolve/index API when monitor privilege is unavailable. This alerts the agent to potential behavior changes based on permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The core purpose is stated first, followed by the fallback detail. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the essential behavior and a notable edge case (missing privilege). It lacks mention of return format, but that is not critical given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (name) has 100% schema coverage, so the description's mention of 'optionally filtered by name' adds minimal new information beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists index aliases, which is a specific verb and resource. It also mentions filtering by name, distinguishing it from sibling tools like get_mapping or get_settings that deal with different index components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the optional name filter and the fallback behavior when cluster monitor privilege is missing. While it doesn't explicitly say when not to use it, the context is clear that this is for listing aliases, and alternatives are implied by sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single document from an index by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id | |
| index | Yes | Index name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the annotation 'readOnlyHint=true' but adds no additional behavioral context. It does not mention what happens if the document is not found, permissions required, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the core functionality efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with 100% schema coverage, the description is mostly sufficient. However, it does not specify the return format or structure, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds no extra meaning beyond the parameter names and types. The phrase 'by its id' reiterates what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch', the resource 'single document from an index', and the method 'by its id'. It distinguishes itself from sibling tools like 'search' which retrieves multiple documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives like 'search' or 'list_indices'. It only implies usage for single document retrieval by id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a Kibana saved object (visualization, lens, dashboard, index-pattern, search, map, tag, ...) by ":" reference. Decodes the JSON-as-string fields Kibana stores inline (visState, searchSourceJSON, ...) and resolves references[] to the titles of the objects they point at. Reads .kibana_analytics and .kibana directly, so the API key needs read access to those indices.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Saved-object reference in "<type>:<id>" form, e.g. "visualization:my-viz-001" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it decodes inline JSON fields and resolves references, beyond the readOnlyHint annotation. Also specifies which indices are accessed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with action, then processing details, then access requirements. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains output characteristics (decoded fields, resolved references) and access needs. Sufficient for a simple fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers ref parameter with description; description adds example format, reinforcing the syntax. Value added over schema is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches a Kibana saved object by type:id reference, with specific examples. Differentiates from siblings by specifying it reads Kibana indices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains use case and prerequisites (API key needs read access to specified indices). Does not explicitly state when not to use or contrast with siblings like get_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the field mappings for one or more indices. Falls back to the read-level _field_caps API (field names and types) when the index "view_index_metadata" privilege is missing.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name, comma-separated list, or pattern |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral info beyond readOnlyHint annotation: falls back to _field_caps API when permission is missing, disclosing potential different behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no unnecessary words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and a key behavioral nuance; no output schema needed for simple tool; missing explanation of response format but that's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, parameter index already well-documented in schema; description adds no further meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the field mappings for one or more indices' with a specific verb and resource, distinguishing it from siblings like get_settings or get_aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on fallback behavior when privilege is missing, but does not explicitly compare with siblings or state when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the settings for one or more indices.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name, comma-separated list, or pattern |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds no further behavioral context. Acceptable but minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, with no unnecessary words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and full annotation coverage, the description suffices. Could briefly mention distinction from sibling get tools, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full description for the only parameter (index). Description adds no additional semantic meaning beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (Get) and resource (settings for one or more indices), distinguishing it from sibling tools like get_mapping or get_aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention any prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List indices with their health, status, document count, and size (equivalent to _cat/indices). Falls back to the index-level _resolve/index API (names only) when the cluster "monitor" privilege is missing.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional index name or pattern to filter the listing |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by disclosing the fallback behavior to _resolve/index API when monitor privilege is absent. This goes beyond the structured data. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and includes essential fallback behavior. Every sentence is necessary and there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, readOnlyHint annotated), the description fully covers what the tool does, what it returns, and a key behavioral edge case. Nothing is missing for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its single optional parameter 'index', describing it as an optional name or pattern for filtering. The description adds no additional parameter semantics beyond restating the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List indices' and specifies the returned fields: health, status, document count, and size. It also explicitly equates the tool to '_cat/indices', making the purpose unambiguous. This distinguishes it from sibling tools like cluster_health which focus on cluster-level metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool, noting that it falls back to a name-only API when the cluster monitor privilege is missing. This implies it works even with limited permissions. However, it does not explicitly state when NOT to use it or name specific alternatives among siblings, hence not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the nodes in the cluster with role, heap, CPU, and load information (equivalent to _cat/nodes).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only (readOnlyHint=true). The description adds context about the specific data returned (role, heap, CPU, load), which goes beyond the annotation. However, it does not disclose any other behavioral traits like performance or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the tool's purpose and the type of information provided. Every word is useful and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description gives enough context via the equivalent _cat/nodes reference and lists fields. It could be more explicit about the response format (e.g., array of node objects), but for a simple read-only list, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description does not need to add parameter semantics, but it clearly states the tool lists nodes without any filtering, which is consistent with the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists nodes in the cluster with specific metrics (role, heap, CPU, load), referencing the equivalent _cat/nodes API. This is a specific verb+resource+info combination that distinguishes it from sibling tools like list_indices or cluster_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear purpose but does not explicitly state when to use this tool versus alternatives like cluster_health or cluster_stats. While it implies usage for node-level metrics, no guidance on exclusions or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the cluster's shards with their primary/replica role, state, document count, store size, and hosting node (equivalent to _cat/shards). The docs and store columns come back null without the cluster "monitor" privilege; there is no lower-privilege source for per-shard rows, so a missing privilege surfaces as an error.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional index name or pattern to filter the shards |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true. Description adds critical context about privilege requirements (monitor) and behavior when missing (null fields, error), enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first covers purpose and output fields, second adds behavioral nuance. Front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema but description lists return fields and explains privilege dependency. For a simple tool with one optional param, this is nearly complete; only minor details like error specifics are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (index). The description does not add any new meaning beyond the schema's description, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists cluster's shards with specific attributes like role, state, document count, etc. It also notes equivalence to _cat/shards, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings like list_indices or cluster_health. The description implies use for shard-level detail but lacks context selection advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an Elasticsearch search using Query DSL and return the matching hits and aggregations.
| Name | Required | Description | Default |
|---|---|---|---|
| aggs | No | Aggregations object | |
| from | No | Offset of the first hit to return | |
| size | No | Number of hits to return (default 10) | |
| sort | No | Sort specification (string, object, or array) | |
| index | Yes | Index name, comma-separated list, or pattern to search | |
| query | No | Query DSL query object, e.g. { "match": { "field": "value" } } | |
| source | No | _source filtering: boolean, field, or array of fields |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds that it returns 'matching hits and aggregations' and uses Query DSL, which provides useful behavioral context beyond annotations. It does not describe potential performance impacts or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's core function and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects, no output schema), the description is minimal. It mentions 'matching hits and aggregations' but does not detail return format or complexity of queries, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description does not add further meaning to any parameters beyond the high-level purpose. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Run an Elasticsearch search using Query DSL and return the matching hits and aggregations.' This is a specific verb+resource (search on Elasticsearch) and clearly distinguishes from sibling tools like 'count' or 'get_document'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'count' for simple counts or 'get_document' for single documents. No exclusions or context for appropriate usage are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.1.0esqlv1.0.0cluster_healthcluster_infocluster_statscountget_aliasesget_documentget_kibana_objectget_mappingget_settingslist_indiceslist_nodeslist_shardssearchEach tool has a clear, distinct purpose: cluster health, info, and stats are separate; index listing, node listing, and shard listing are distinct; get operations for documents, aliases, mappings, settings, and Kibana objects are well-separated. No two tools overlap in functionality.
Most tool names follow a consistent verb_noun pattern (e.g., get_document, list_indices, list_nodes). However, cluster_health, cluster_info, cluster_stats are noun phrases without a verb prefix, and count and search are bare verbs, introducing minor inconsistency.
With 13 tools, the set is well-scoped for an Elasticsearch server covering cluster, index, document, search, and Kibana object operations. It is neither too sparse nor overwhelming, fitting a typical agent's needs.
The tool set excels at read operations (cluster health, stats, listings, document fetch, search) but lacks any write operations such as creating indices, updating documents, or managing mappings. This gap limits common CRUD workflows that users might expect from an Elasticsearch interface.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A Model Context Protocol server for Wix AI tools
MCP server for searching Airweave collections with natural language queries.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/csimi/elastic-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
