Elastic MCP server: Agent Builder setup, tools and limits

Elastic serves MCP from Kibana through Agent Builder. The standalone server is deprecated, and its npm package ships fewer tools than its README lists.

Checked 7 October 2026 · from Elastic's Agent Builder documentation, the standalone repository and npm registry, and that server's own tools/list response

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

What is the Elastic MCP server?

It is Elastic's server for the Model Context Protocol, served by Kibana. An external client such as Claude Code or Cursor calls Agent Builder tools without opening Kibana.

ES|QL is Elastic's piped query language. platform.core.generate_esql writes a query from a plain question, and platform.core.execute_esql runs it.

There are two surfaces and only one is developed. The Agent Builder MCP endpoint is current. The standalone server, @elastic/mcp-server-elasticsearch, is deprecated, and its npm package stops at 0.3.1 with four tools.

Elastic has two MCP servers, and one is current:

The standalone server's README and its npm entry both carry the deprecation notice, and the README points to Agent Builder.

Elastic's Agent Builder endpoint reaches indices and ES|QL everywhere, and logs, traces and alerts in Observability. It concerns queried operational data, so development workflow, model traces and billing sit outside it.

For an agent, Elastic answers questions about data already in Elasticsearch. An agent connected here can search logs, run ES|QL, and read traces and alerts. It cannot see the code change behind an incident, so it pairs with a source-control connector.

What can an AI agent do with Elastic?

Tool IDs follow Elastic's built-in tools reference, read 7 October 2026. The deprecated standalone server covered only the first two rows, with four tools.

What the tool definitions cost in context

A client that loads every tool definition at the start of a session spends this much context before the first question. Claude Code defers definitions by default through tool search, and loads a tool's definition when the agent needs it. The method below gives the version and date measured.

A context window is the amount of text a model can hold at once. A client that loads every tool definition upfront sends each tool's name, description and input schema to the model when the session starts. That list is charged whether or not a single tool is called.

The figures below were measured on the deprecated standalone server's npm package on 19 August 2026. Its four tools cost about 374 tokens. Agent Builder serves its catalog only to an authenticated deployment, and the catalog changes by version, so it is unmeasured.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 19 August 2026 from tools/list on the deprecated @elastic/mcp-server-elasticsearch 0.3.1, the npm latest. It was run locally with a placeholder URL and key.

Registration is static, so no Elasticsearch instance was involved. Figures cover name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 56%. Reasoning tokens are output, spent per request. This count is billed as input whenever the client loads it.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. The definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is a small fraction.

Elastic MCP server limits: where answers come back incomplete

The first two limits below return answers that look complete. The third applies to setups still running the deprecated standalone server.

How to configure Elastic MCP for agents

1. 1

   Check your version and license

   The Agent Builder MCP endpoint is generally available from Elastic 9.3 and in preview on 9.2. Outside Serverless, Elastic's subscription table lists MCP access under Enterprise.

2. 2

   Pick an API key or OAuth

   An API key works on every deployment and suits unattended agents. OAuth 2.1 works on Serverless only, and gives each person their own revocable connection.

3. 3

   Scope the API key

   Tools run with the key's permissions. Restrict it to the indices the agent should read, and include the feature_agentBuilder.read Kibana privilege, which the endpoint requires.

4. 4

   Include the space in the URL

   A custom Kibana Space needs /s/<space-name> before /api/agent_builder/mcp. On 9.2, the copy button in the Tools UI leaves the space out.

5. 5

   Keep the standalone server for clusters older than 9.2 only

   It receives critical security fixes and nothing else, and its npm package stops at 0.3.1.

Paste this into your agent’s instructions

Agent Builder returns what the key may read, so its silent failure is scope. An agent that searched one index sounds the same as one that searched everything.

When you answer using Elastic MCP tools, state:
- Which indices or data streams you searched, and the
  time range in the query.
- The tool you used, and the ES|QL or query it ran.
- Whether the result hit a size limit. A full page of hits
  is not evidence there are no more.
Report an empty result as "none returned under the
constraints above".
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Partly. Elasticsearch's REST API and ES|QL are fully documented, and a coding agent can call them directly with the same API key.

Agent Builder adds tools above the raw API: ES|QL generation, index exploration from a plain question, and the Observability analysis tools. Custom tools you define in Kibana reach the agent through the same endpoint.

For a cluster older than 9.2, the deprecated standalone server still wraps _cat/indices, _mapping, _search and _cat/shards in four tools. It receives security fixes only.

On Elastic 9.2 or later, use the Agent Builder endpoint. On older clusters, use the REST API or the standalone server, and plan the upgrade.

Elastic MCP server setup

The MCP endpoint is built into Kibana, so there is nothing to install. It is <kibana-url>/api/agent_builder/mcp, or <kibana-url>/s/<space-name>/api/agent_builder/mcp in a custom space.

Authenticate with an API key that carries the feature_agentBuilder.read Kibana privilege, sent as Authorization: ApiKey <key>. Serverless projects also accept OAuth 2.1.

claude mcp add --transport http elastic \
  https://<kibana-url>/api/agent_builder/mcp \
  --header "Authorization: ApiKey <your-api-key>"

{"mcpServers":{"elastic-agent-builder":{"command":"npx",
  "args":["mcp-remote","https://<kibana-url>/api/agent_builder/mcp",
    "--header","Authorization:${AUTH_HEADER}"],
  "env":{"AUTH_HEADER":"ApiKey <your-api-key>"}}}}

[mcp_servers.elastic]
url = "https://<kibana-url>/api/agent_builder/mcp"
env_http_headers = { Authorization = "ELASTIC_AUTH_HEADER" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"elastic-agent-builder":{"command":"npx",
  "args":["mcp-remote","https://<kibana-url>/api/agent_builder/mcp",
    "--header","Authorization:${AUTH_HEADER}"],
  "env":{"AUTH_HEADER":"ApiKey <your-api-key>"}}}}

{"mcpServers":{"elastic":{
  "httpUrl":"https://<kibana-url>/api/agent_builder/mcp",
  "headers":{"Authorization":"ApiKey <your-api-key>"}}}}

{"servers":{"elastic":{"type":"http",
  "url":"https://<kibana-url>/api/agent_builder/mcp",
  "headers":{"Authorization":"ApiKey <your-api-key>"}}}}

{"mcpServers":{"elastic":{"type":"http",
  "url":"https://<kibana-url>/api/agent_builder/mcp",
  "headers":{"Authorization":"ApiKey <your-api-key>"}}}}

claude mcp add-json "elasticsearch" '{"command":"npx",
  "args":["-y","@elastic/mcp-server-elasticsearch"],
  "env":{"ES_URL":"https://your-cluster:9200",
         "ES_API_KEY":"<your-api-key>"}}'

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

Read-only access, permissions and security

• Tools run with the API key's permissions

  Elastic's guidance is to restrict the key to the indices the tools need, and to set an expiry date on it.

• Some built-in tools write

  From 9.4 the catalog includes security.create_detection_rule, and 9.5 adds watchlist and case management tools. A key with read privileges only keeps writes out of reach.

• One key is one identity

  Every caller that shares an API key acts with the same permissions. On Serverless, OAuth gives each person their own connection, revocable one at a time.

• The standalone server gets security fixes only

  Elastic deprecated it with v0.4.6 on 24 October 2025. Move to Agent Builder on 9.2 or later.

Troubleshooting

403 Forbidden on connect

The API key lacks the feature_agentBuilder.read Kibana application privilege. Create a key that includes it.

Tools from a custom space are missing

The URL needs /s/<space-name> before /api/agent_builder/mcp. On 9.2, the copy button in the Tools UI leaves the space name out.

An OAuth connection stops working

OAuth tokens refresh automatically, but a connection unused for 30 days or more needs a new authorization. OAuth applies to Serverless projects only.

There is no tool for ES|QL

That is the deprecated standalone server's npm package, 0.3.1, which registers four tools. Agent Builder provides platform.core.execute_esql. The standalone 0.4.x Docker image also has esql.

The SSE transport fails

SSE is deprecated on the standalone server. Configure streamable HTTP, or stdio for a local process.

Elastic MCP server: Reference

What engineers report

Agent Builder ships inside Kibana, so its record is Elastic's documentation. The public repository belongs to the deprecated standalone server, with 717 stars as of 7 October 2026.

“The get_mappings tool throws error decoding response body if a nested property is defined without explicitly specifying nested, even though the mapping is valid according to Elasticsearch specifications.”

“I deployed the MCP Server using docker and entered the container to confirm that the environment variables ES_USERNAME, ES_PASSWORD, and even ES_lOGIN configuration were all correct. However, it still said that my identity authentication failed.”

Repository facts from the GitHub API and package facts from the npm registry, retrieved 7 October 2026. Agent Builder facts from Elastic's documentation, read 7 October 2026. The standalone tool count comes from that server's own tools/list response on 19 August 2026.

Should you connect an agent to Elastic?

Yes. Best for elastic 9.3+ and Serverless teams, with a read-only API key scoped to the indices the agent needs.

Strongest fit

Teams on Elastic 9.3 or later, or Serverless, who want an agent searching indices, running ES|QL and reading Observability data.

Main advantage

Built into Kibana, with ES|QL generation, Observability analysis tools and your own custom tools on one endpoint.

Main weakness

Outside Serverless it needs an Enterprise subscription, and the tool catalog changes from version to version.

Operational risk

Tools run with the API key's privileges, and some built-in tools write. A broadly scoped key gives the agent that reach.

Frequently asked questions