Set up the Elastic Agent Builder MCP Server

The Elastic Agent Builder MCP Server is not a separate program but an endpoint that becomes automatically available once Agent Builder is active on a Kibana instance. This guide covers the basic steps from activation to a first connection with an AI client.

Prerequisites

You need a Kibana instance with Agent Builder — generally available in the Elastic Stack from version 9.3, shipped as a preview from 9.2, and generally available on Elastic Cloud Serverless. You also need at least one configured tool (a built-in one such as ES|QL queries, or a custom one) and either an API key or, on Serverless, an OAuth 2.1 client with the appropriate Agent Builder permissions.

Enable Agent Builder and create tools

In Kibana, you'll find Agent Builder under the AI features. From there you can use built-in tools directly or build targeted, custom tools — for example a semantic search over a specific index or an ES|QL tool for a recurring metrics query. Each tool gets a name and a description intended for the model.

Find the server URL

The MCP server URL is shown in the Tools view of Agent Builder and follows the pattern {KIBANA_URL}/api/agent_builder/mcp. If you work in a custom Kibana space, the path gains the space name: {KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp.

Connect an MCP client

For automation and single applications, an Elastic API key is the simplest path: add the server URL together with the API key to your client's configuration file, for example ~/.cursor/mcp.json in Cursor. In a CLI client such as Claude Code, you can register the server for testing following this pattern, replacing the angle brackets with your own Kibana URL:

claude mcp add --transport http elastic-agent-builder https://<kibana-url>/api/agent_builder/mcp

On Serverless projects, OAuth 2.1 is also available, useful for interactive, multi-person scenarios: each signed-in person then gets individually revocable permissions instead of a shared key.

Keep permissions narrow

Create a dedicated, narrowly scoped API key for MCP access instead of reusing an existing, broadly privileged one. Since every tool acts with exactly that key's permissions, the Kibana role behind it determines which indices and tools an AI client can actually see and run.

Verifying the setup

Ask the client a simple question matching a configured tool, such as an ES|QL metrics question. If the agent returns a plausible result based on real data instead of a permission or connection error, the setup is correct.

Common pitfalls

A frequent mistake is an API key lacking sufficient Kibana permissions for Agent Builder — the call then fails with a permission error rather than simply returning nothing. A second pitfall involves custom Kibana spaces: forgetting the space name in the endpoint path means the client cannot find the server. Anyone planning to use OAuth 2.1 should also confirm the project is actually Serverless, since that authentication method is not available on Stack deployments.