MCP server Technical Preview

POST /api/agent_builder/mcp
Api key auth

Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.

[Required authorization] Route required privileges: read_onechat.

application/json

Body

Responses

  • 200 application/json

    Indicates a successful response

POST /api/agent_builder/mcp 
curl \
 --request POST 'https://<KIBANA_URL>/api/agent_builder/mcp' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":1,"method":"initialize","params":{"clientInfo":{"name":"test-client","version":"1.0.0"},"capabilities":{},"protocolVersion":"2024-11-05"},"jsonrpc":"2.0"}'
Request example
Example request to initalise communication over MCP protocol 
{
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    },
    "capabilities": {},
    "protocolVersion": "2024-11-05"
  },
  "jsonrpc": "2.0"
}
Response examples (200)
Example response showing the successful result of communication initialisation over MCP protocol 
{
  "id": 1,
  "result": {
    "serverInfo": {
      "name": "elastic-mcp-server",
      "version": "0.0.1"
    },
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "protocolVersion": "2024-11-05"
  },
  "jsonrpc": "2.0"
}

APM server schema

Create APM fleet server schema.

Cancel an agent action

POST /api/fleet/agents/actions/{actionId}/cancel
Api key auth

[Required authorization] Route required privileges: fleet-agents-all.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • actionId string Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • agents array[string]
      • created_at string Required
      • expiration string
      • id string Required
      • minimum_execution_duration number
      • namespaces array[string]
      • rollout_duration_seconds number
      • sent_at string
      • source_uri string
      • start_time string
      • total number
      • type string Required
  • 400 application/json
    Hide response attributes Show response attributes object
    • error string
    • errorType string
    • message string Required
    • statusCode number
POST /api/fleet/agents/actions/{actionId}/cancel 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/actions/{actionId}/cancel' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Elastic Agent binary download sources

Elastic Agent binary download sources APIs enable you to manage download sources for Elastic Agent binaries, including creating, updating, and deleting custom download sources for agent binaries.

Get an enrollment API key

GET /api/fleet/enrollment_api_keys/{keyId}
Api key auth

Get an enrollment API key by ID.

[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.

Path parameters

  • keyId string Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • hidden boolean
      • id string Required
      • name string

        The name of the enrollment API key.

      • policy_id string

        The ID of the agent policy the Elastic Agent will be enrolled in.
  • 400 application/json
    Hide response attributes Show response attributes object
    • error string
    • errorType string
    • message string Required
    • statusCode number
GET /api/fleet/enrollment_api_keys/{keyId} 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys/{keyId}' \
 --header "Authorization: $API_KEY"

Get proxies

GET /api/fleet/proxies
Api key auth

[Required authorization] Route required privileges: fleet-settings-read.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • certificate string | null
      • certificate_authorities string | null
      • certificate_key string | null
      • id string Required
      • is_preconfigured boolean

        Default value is false.

      • name string Required
      • proxy_headers object | null
      • url string Required
    • page number Required
    • perPage number Required
    • total number Required
  • 400 application/json
    Hide response attributes Show response attributes object
    • error string
    • errorType string
    • message string Required
    • statusCode number
GET /api/fleet/proxies 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/proxies' \
 --header "Authorization: $API_KEY"

Fleet Server hosts

Fleet Server hosts APIs enable you to manage Fleet Server hosts, including creating, updating, and deleting Fleet Server host configurations.

Get a Fleet Server host

GET /api/fleet/fleet_server_hosts/{itemId}
Api key auth

Get a Fleet Server host by ID.

[Required authorization] Route required privileges: fleet-settings-read.

Path parameters

  • itemId string Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • host_urls array[string] Required

        At least 1 element.

      • id string Required
      • is_default boolean

        Default value is false.

      • is_internal boolean
      • is_preconfigured boolean

        Default value is false.

      • name string Required
      • proxy_id string | null
      • secrets object

        Additional properties are NOT allowed.

        Hide secrets attribute Show secrets attribute object
      • ssl object | null

        Additional properties are NOT allowed.

        Hide ssl attributes Show ssl attributes object | null
        • agent_certificate string
        • agent_certificate_authorities array[string]
        • agent_key string
        • certificate string
        • certificate_authorities array[string]
        • client_auth string

          Values are optional, required, or none.

        • es_certificate string
        • es_certificate_authorities array[string]
        • es_key string
        • key string
  • 400 application/json
    Hide response attributes Show response attributes object
    • error string
    • errorType string
    • message string Required
    • statusCode number
GET /api/fleet/fleet_server_hosts/{itemId} 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId}' \
 --header "Authorization: $API_KEY"

Observability AI Assistant

Interact with the Observability AI Assistant resources.

Observability AI Assistant

Create or update a role

PUT /api/security/role/{name}
Api key auth

Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • name string Required

    The role name.

    Minimum length is 1, maximum length is 1024.

Query parameters

  • createOnly boolean

    When true, a role is not overwritten if it already exists.

    Default value is false.

application/json

Body

  • description string

    A description for the role.

    Maximum length is 2048.

  • elasticsearch object Required

    Additional properties are NOT allowed.

    Hide elasticsearch attributes Show elasticsearch attributes object
    • cluster array[string]

      Cluster privileges that define the cluster level actions that users can perform.

    • indices array[object]
      Hide indices attributes Show indices attributes object
      • allow_restricted_indices boolean

        Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.

      • field_security object
        Hide field_security attribute Show field_security attribute object
        • * array[string] Additional properties

          The document fields that the role members have read access to.

      • names array[string] Required

        The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).

        At least 1 element.

      • privileges array[string] Required

        The index level privileges that the role members have for the data streams and indices.

        At least 1 element.

      • query string

        A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.

    • remote_cluster array[object]
      Hide remote_cluster attributes Show remote_cluster attributes object
      • clusters array[string] Required

        A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

        At least 1 element.

      • privileges array[string] Required

        The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.

        At least 1 element.

    • remote_indices array[object]
      Hide remote_indices attributes Show remote_indices attributes object
      • allow_restricted_indices boolean

        Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.

      • clusters array[string] Required

        A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

        At least 1 element.

      • field_security object
        Hide field_security attribute Show field_security attribute object
        • * array[string] Additional properties

          The document fields that the role members have read access to.

      • names array[string] Required

        A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).

        At least 1 element.

      • privileges array[string] Required

        The index level privileges that role members have for the specified indices.

        At least 1 element.

      • query string

        A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.

    • run_as array[string]

      A user name that the role member can impersonate.

  • kibana array[object]
    Hide kibana attributes Show kibana attributes object
  • metadata object

    Additional properties are allowed.

Responses

  • 204

    Indicates a successful call.

PUT /api/security/role/{name} 
curl \
 --request PUT 'https://<KIBANA_URL>/api/security/role/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}}'

Finds Attack discovery schedules that match the search criteria

GET /api/attack_discovery/schedules/_find
Api key auth

Finds Attack discovery schedules that match the search criteria. Supports pagination and sorting by various fields.

Query parameters

  • page number

    Page number to return (used for pagination). Defaults to 1.

  • per_page number

    Number of Attack discovery schedules to return per page (used for pagination). Defaults to 10.

  • sort_field string(nonempty)

    Field used to sort results. Common fields include 'name', 'created_at', 'updated_at', and 'enabled'.

    Minimum length is 1.

  • sort_direction string

    Sort order direction. Use 'asc' for ascending or 'desc' for descending. Defaults to 'asc'.

    Values are asc or desc.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required

      Array of matched Attack discovery schedule objects.

      An attack discovery schedule

      Hide data attributes Show data attributes object
      • actions array[object] Required

        The attack discovery schedule actions

        Hide actions attributes Show actions attributes object
        • action_type_id string Required

          The action type used for sending notifications.

        • alerts_filter object

          Additional properties are allowed.

        • frequency object

          The action frequency defines when the action runs (for example, only on schedule execution or at specific time intervals).

          Hide frequency attributes Show frequency attributes object
          • notify_when string Required

            The condition for throttling the notification: onActionGroupChange, onActiveAlert, or onThrottleInterval

            Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.

          • summary boolean Required

            Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

          • throttle string Required

            Defines how often schedule actions are taken. Time interval in seconds, minutes, hours, or days.

            Format should match the following pattern: ^[1-9]\d*[smhd]$.

        • group string

          Groups actions by use cases. Use default for alert notifications.

        • id string Required

          The connector ID.

        • params object Required

          Object containing the allowed connector fields, which varies according to the connector type.

          Additional properties are allowed.

        • uuid string(nonempty)

          A string that does not contain only whitespace characters.

          Minimum length is 1.

      • created_at string(date-time) Required

        The date the schedule was created

      • created_by string Required

        The name of the user that created the schedule

      • enabled boolean Required

        Indicates whether the schedule is enabled

      • id string Required

        UUID of attack discovery schedule

      • last_execution object

        An attack discovery schedule execution information

        Hide last_execution attributes Show last_execution attributes object
        • date string(date-time) Required

          Date of the execution

        • duration number

          Duration of the execution

        • message string
        • status string Required

          An attack discovery schedule execution status

          Values are ok, active, error, unknown, or warning.

      • name string Required

        The name of the schedule

      • params object Required

        An attack discovery schedule params

        Hide params attributes Show params attributes object
        • alerts_index_pattern string Required

          The index pattern to get alerts from

        • api_config object Required

          LLM API configuration.

          Hide api_config attributes Show api_config attributes object
          • actionTypeId string Required

            Action type ID

          • connectorId string Required

            Connector ID

          • defaultSystemPromptId string

            Default system prompt ID

          • model string

            Model

          • provider string

            Provider

            Values are OpenAI, Azure OpenAI, or Other.

          • name string Required

            The name of the connector

        • combined_filter object

          Additional properties are allowed.

        • end string
        • filters array

          The filter array used to define the conditions for when alerts are selected as an attack discovery context. Defaults to an empty array.

        • query object

          An query condition to filter alerts

          Hide query attributes Show query attributes object
        • size number Required
        • start string
      • schedule object Required
        Hide schedule attribute Show schedule attribute object
        • interval string Required

          The schedule interval

      • updated_at string(date-time) Required

        The date the schedule was updated

      • updated_by string Required

        The name of the user that updated the schedule

    • page number Required

      Current page number of the paginated result set.

    • per_page number Required

      Number of items requested per page.

    • total number Required

      Total number of Attack discovery schedules matching the query (across all pages).
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
    • error string

      Error type

    • message string

      Human-readable error message

    • status_code number

      HTTP status code
GET /api/attack_discovery/schedules/_find 
curl \
 --request GET 'http://localhost:5601/api/attack_discovery/schedules/_find?page=1&per_page=10&sort_field=name&sort_direction=asc' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json"

Read a Knowledge Base Entry

GET /api/security_ai_assistant/knowledge_base/entries/{id}
Api key auth

Retrieve a Knowledge Base Entry by its unique id.

Path parameters

  • id string(nonempty) Required

    The unique identifier (id) of the Knowledge Base Entry to retrieve.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful request returning the requested Knowledge Base Entry.

    Any of:
    Security_AI_Assistant_API_DocumentEntry object Security_AI_Assistant_API_IndexEntry object
    Hide attributes Show attributes
    • global boolean Required

      Whether this Knowledge Base Entry is global, defaults to false.

    • name string Required

      Name of the Knowledge Base Entry.

    • namespace string Required

      Kibana Space, defaults to 'default' space.

    • users array[object] Required

      Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

      Could be any string, not necessarily a UUID.

      Hide users attributes Show users attributes object
      • id string

        User id.

      • name string

        User name.

    • createdAt string Required

      Time the Knowledge Base Entry was created.

    • createdBy string Required

      User who created the Knowledge Base Entry.

    • id string(nonempty) Required

      A string that does not contain only whitespace characters.

      Minimum length is 1.

    • updatedAt string Required

      Time the Knowledge Base Entry was last updated.

    • updatedBy string Required

      User who last updated the Knowledge Base Entry.

    • kbResource string Required

      Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc.

      Values are security_labs, defend_insights, or user.

    • source string Required

      Source document name or filepath.

    • text string Required

      Knowledge Base Entry content.

    • type string Required Discriminator

      Entry type.

    • required boolean

      Whether this resource should always be included, defaults to false.

    • vector object

      Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings.

      • tokens object Required

        Tokens with their corresponding values.

        Hide tokens attribute Show tokens attribute object
        • * number Additional properties
  • 400 application/json

    A generic error occurred, such as an invalid id or the entry not being found.

    Hide response attributes Show response attributes object
    • error string Required

      Error type or category.

    • message string Required

      Detailed error message.

    • statusCode number Required

      HTTP status code of the error.
GET /api/security_ai_assistant/knowledge_base/entries/{id} 
curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/12345' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "id": "12345",
  "tags": [
    "password",
    "reset",
    "help"
  ],
  "title": "How to reset a password",
  "content": "To reset your password, go to the settings page and click 'Reset Password'."
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "No Knowledge Base Entry found with the provided `id`."
}

Deletes a single Knowledge Base Entry using the `id` field

DELETE /api/security_ai_assistant/knowledge_base/entries/{id}
Api key auth

Delete a Knowledge Base Entry by its unique id.

Path parameters

  • id string(nonempty) Required

    The unique identifier (id) of the Knowledge Base Entry to delete.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful request returning the id of the deleted Knowledge Base Entry.

    Hide response attribute Show response attribute object
    • id string(nonempty) Required

      A string that does not contain only whitespace characters.

      Minimum length is 1.
  • 400 application/json

    A generic error occurred, such as an invalid id or the entry not being found.

    Hide response attributes Show response attributes object
    • error string Required

      Error type or category.

    • message string Required

      Detailed error message.

    • statusCode number Required

      HTTP status code of the error.
DELETE /api/security_ai_assistant/knowledge_base/entries/{id} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/12345' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "id": "12345",
  "message": "Knowledge Base Entry successfully deleted."
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "No Knowledge Base Entry found with the provided `id`."
}