Loading

Elastic Agent Builder MCP server

The Model Context Protocol (MCP) server provides a standardized interface for external clients to access Elastic Agent Builder tools.

The MCP server is available at:

{KIBANA_URL}/api/agent_builder/mcp

When using a custom Kibana Space, include the space name in the URL:

{KIBANA_URL}/s/{SPACE_NAME}/api/agent_builder/mcp
Tip

You can copy your MCP server URL directly in the Tools GUI. Refer to Tools in Elastic Agent Builder > Copy your MCP server URL.

Most MCP clients (such as Claude Desktop, Cursor, VS Code, etc.) have similar configuration patterns. To connect to your Elastic instance, you need to provide your Kibana URL and API key in the client's configuration file, typically in the following format:

{
  "mcpServers": {
    "elastic-agent-builder": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "${KIBANA_URL}/api/agent_builder/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "KIBANA_URL": "${KIBANA_URL}",
        "AUTH_HEADER": "ApiKey ${API_KEY}"
      }
    }
  }
}
  1. Refer to Elastic Agent Builder MCP server > API key application privileges
Note

Set the following environment variables:

export KIBANA_URL="your-kibana-url"
export API_KEY="your-api-key"

For information on generating API keys, refer to Elastic API keys.

Tools execute with the scope assigned to the API key. Make sure your API key has the appropriate permissions to only access the indices and data that you want to expose through the MCP server. To learn more, refer to Elastic Agent Builder MCP server > API key application privileges.

To access the MCP server endpoint, your API key must include Kibana application privileges for Elastic Agent Builder.

POST /_security/api_key
{
  "name": "my-mcp-api-key",
  "expiration": "30d",
  "role_descriptors": {
    "mcp-access": {
      "indices": [
        {
          "names": ["*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ],
      "applications": [
        {
          "application": "kibana-.kibana",
          "privileges": ["feature_agentBuilder.read"],
          "resources": ["space:default"]
        }
      ]
    }
  }
}
Note

Without the feature_agentBuilder.read application privilege, you'll receive a 403 Forbidden error when attempting to connect to the MCP endpoint.

Always set an expiration date on API keys for security. Use shorter durations (1-7 days) for development and longer durations (30-90 days) for production, rotating keys regularly.

For production environments, restrict API keys to only the indices your tools need to access. This follows the principle of least privilege and prevents agents from querying sensitive data.

POST /_security/api_key
{
  "name": "my-mcp-api-key",
  "expiration": "30d",
  "role_descriptors": {
    "mcp-access": {
      "indices": [
        {
          "names": ["logs-*", "metrics-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ],
      "applications": [
        {
          "application": "kibana-.kibana",
          "privileges": ["feature_agentBuilder.read"],
          "resources": ["space:default"]
        }
      ]
    }
  }
}
  1. Restrict index access to only the indices your tools need to query. Adjust the index patterns based on your security requirements.
  2. Read-only privileges prevent the agent from modifying data.
  3. Must be exactly kibana-.kibana - this is how Kibana registers its application privileges with Elasticsearch.