diff --git a/solutions/search/agent-builder/mcp-server.md b/solutions/search/agent-builder/mcp-server.md index d9a1180e34..b486d58d91 100644 --- a/solutions/search/agent-builder/mcp-server.md +++ b/solutions/search/agent-builder/mcp-server.md @@ -40,12 +40,13 @@ Most MCP clients (such as Claude Desktop, Cursor, VS Code, etc.) have similar co ], "env": { "KIBANA_URL": "${KIBANA_URL}", - "AUTH_HEADER": "ApiKey ${API_KEY}" + "AUTH_HEADER": "ApiKey ${API_KEY}" <1> } } } } ``` +1. Refer to [](#api-key-application-privileges) :::{note} Set the following environment variables: @@ -57,5 +58,63 @@ export API_KEY="your-api-key" For information on generating API keys, refer to [API keys](https://www.elastic.co/docs/solutions/search/search-connection-details). -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. +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 [](#api-key-application-privileges). ::: + +## API key application privileges + +To access the MCP server endpoint, your API key must include {{kib}} application privileges. + +### Development and testing + +For development and testing purposes, you can create an unrestricted API key with full access: + +```json +POST /_security/api_key +{ + "name": "my-mcp-api-key", + "expiration": "1d", + "role_descriptors": { + "unrestricted": { + "cluster": ["all"], + "indices": [ + { + "names": ["*"], + "privileges": ["all"] + } + ] + } + } +} +``` + +### Production + +For production environments, use a restricted API key with specific application privileges: + +```json +POST /_security/api_key +{ + "name": "my-mcp-api-key", + "expiration": "1d", + "role_descriptors": { + "mcp-access": { + "cluster": ["all"], + "indices": [ + { + "names": ["*"], + "privileges": ["read", "view_index_metadata"] + } + ], + "applications": [ + { + "application": "kibana-.kibana", + "privileges": ["read_onechat", "space_read"], <1> + "resources": ["space:default"] + } + ] + } + } +} +``` +1. The `read_onechat` and `space_read` application privileges are required to authorize access to the MCP endpoint. Without these privileges, you'll receive a 403 Forbidden error.