---
title: Authenticate MCP clients with API keys
description: Configure external MCP hosts to connect to the Agent Builder MCP server using API keys.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server-api-keys
products:
  - Elastic Cloud Serverless
  - Elastic Observability
  - Elastic Security
  - Elasticsearch
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3, Preview in 9.2
---

# Authenticate MCP clients with API keys
The [Elastic Agent Builder MCP server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/explore-analyze/ai-features/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.
<tip applies-to="Elastic Cloud Serverless: Preview">
  In Serverless projects, MCP clients can also authenticate using OAuth 2.1 through an [application connection](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/deploy-manage/app-connections/oauth-clients). To compare authentication options, refer to [MCP server authentication](/elastic/docs-content/pull/7104/explore-analyze/ai-features/agent-builder/mcp-server#mcp-server-authentication).
</tip>


## Step 1: Create an API key

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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/deploy-manage/api-keys/elasticsearch-api-keys)
- Serverless: [Serverless project API keys](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/deploy-manage/api-keys/serverless-project-api-keys), or [Elastic Cloud API keys](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7104/deploy-manage/api-keys/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](#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.
```json
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"]
        }
      ]
    }
  }
}
```

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


## Step 2: Configure your MCP client

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:
```json
{
  "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}" 
      }
    }
  }
}
```

<note>
  Set the following environment variables:
  ```bash
  export KIBANA_URL="your-kibana-url"
  export API_KEY="your-api-key"
  ```
</note>


## Best practices


### Set API key expiration dates

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.

### Limit Agent Builder to specific indices

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.
```json
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"]
        }
      ]
    }
  }
}
```