Authenticate MCP clients with API keys

The Elastic Agent Builder MCP server supports API key authentication for MCP clients. For example, you can let a scheduled script or automated service query your data through Elastic Agent Builder tools without a person signing in.

Before configuring your MCP client, create an API key with Kibana application privileges for Elastic Agent Builder. You can use the following key types:

• Elastic Stack: Elasticsearch API keys
• Serverless: Serverless project API keys, or Elastic Cloud API keys with Elasticsearch and Kibana API access.

Tools execute with the scope assigned to the API key. Restrict your key to only the indices and data you want to expose through the MCP server. Refer to Best practices for additional recommendations.

The following example creates an Elasticsearch API key or Serverless project API key with Kibana application privileges for Elastic Agent Builder.

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

1. Required to use Elasticsearch inference endpoints. You can also use "cluster": ["all"] for broader access during development.
2. Must be exactly kibana-.kibana. This is how Kibana registers its application privileges with Elasticsearch. Without the feature_agentBuilder.read privilege, you'll receive a 403 Forbidden error.

Configure a client connection in MCP hosts such as Claude Desktop, Cursor, or VS Code by adding your Kibana URL and API key, 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 Authenticate MCP clients with API keys > Step 1: Create an API key

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

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": {
      "cluster": ["monitor_inference"],
      "indices": [
        {
          "names": ["logs-*", "metrics-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ],
      "applications": [
        {
          "application": "kibana-.kibana",
          "privileges": ["feature_agentBuilder.read", "feature_actions.read"],
          "resources": ["space:default"]
        }
      ]
    }
  }
}

1. Required to use Elasticsearch inference endpoints. You can also use "cluster": ["all"] for broader access during development.
2. Restrict index access to only the indices your tools need to query. Adjust the index patterns based on your security requirements.
3. Read-only privileges prevent the agent from modifying data.
4. Must be exactly kibana-.kibana - this is how Kibana registers its application privileges with Elasticsearch.