Repository navigation
MCP Mutation Kinds
Each mutation class adds planner tools to the MCP server. A planner reads the
stack, stores a plan, and writes nothing; plan_apply applies the plan after a
person confirms it. MCP Mutations covers starting the
server, the confirmation form, plan states, and errors. Each plan sends one
write request:
| Class | Planner tools | Write per plan |
|---|---|---|
rules-toggle |
rules_set_enabled_plan |
POST /api/detection_engine/rules/_bulk_action |
alerts-triage |
alerts_set_status_plan, alerts_set_tags_plan
|
POST /api/detection_engine/signals/status or POST /api/detection_engine/signals/tags
|
cases |
cases_create_plan, cases_comment_plan, cases_set_status_plan
|
POST /api/cases, POST /api/cases/<id>/comments, or PATCH /api/cases
|
rules-create |
rules_create_plan |
POST /api/detection_engine/rules |
- Unknown input keys fail. String inputs must contain non-whitespace text and
are used unchanged. Limits count UTF-8 bytes. A value outside a limit is
invalid_argumentbefore any request. - A plan names each object by identity:
rule_id, alert_id, or case id. It holds at most 20 objects and never lists one twice. - Text the plan writes must show in the form exactly as it is stored. A case
title, description, or comment, or a tag, that holds a control character
other than a line feed (a tab, for example), DEL, a Unicode line or
paragraph separator, or a bidirectional control is
invalid_argument. - An organization-level Elastic Cloud API key (realm
_cloud_api_key) is refused withcredential_unsuitablefor every kind, before any other read. It reaches the whole organization and its role scope cannot be read, so a plan cannot show what it may do. Use a scoped key (which key). - The form's action line holds one line. A case title read from the stack
shows each line break there as U+FFFD, and a new case title with a line break
is
invalid_argument. The first three lines always hold the action, the target, and the first object. - No kind is exactly reversible. What a second call leaves lists what each kind does not restore.
rules_set_enabled_plan enables or disables named rules.
| Input | Value |
|---|---|
selectors |
1 to 20 unique strings, each a rule_id or exact rule name of at most 1,024 bytes |
enabled |
Boolean, required |
- Each selector resolves to a
rule_idasrules_getdoes; see Selectors. Two selectors that resolve to the same rule fail withinvalid_argument. - A read that returns a rule with another
rule_idthan the one asked for fails withelastic_conflict, and no plan is stored. - Each detail line is
<rule_id> <name> <from> -> <to>. A rule already in the requested state stays in the plan asenabled -> enabledordisabled -> disabled. -
cli_equivalentisrules enableorrules disablewith therule_idvalues. - A drift check compares each rule's content. Fields the server maintains,
such as
revision, update times, and execution status, do not count.
The Note: line of a rule toggle:
Note: Kibana runs each rule listed with the credential it already has. A rule that has none gets this server's credential (<12 hex>) when it is enabled, and then runs with that credential's privileges.
alerts_set_status_plan sets the workflow status of alerts named by id.
| Input | Value |
|---|---|
alert_ids |
1 to 20 unique alert _id strings, each at most 1,024 bytes |
status |
open, acknowledged, or closed
|
reason |
Optional, only with closed: false_positive, duplicate, true_positive, benign_positive, automated_closure, or other
|
alerts_set_tags_plan adds and removes workflow tags on alerts named by id.
| Input | Value |
|---|---|
alert_ids |
As above |
add, remove
|
0 to 10 unique strings each, each at most 256 bytes. At least one tag in total, and no tag in both lists |
- The class cannot select alerts by query and cannot assign alerts. Use
alerts close --queryandalerts assignin the CLI for those. - A status plan shows
<_id> <rule name> <from> -> <to>per alert, oralready <status>, thenreason: <reason>when set. A tags plan shows<_id> <rule name> +<tag> -<tag>per alert. It names the edit, not the alert's full tag set. -
cli_equivalentisalerts ack,alerts open, oralerts closewith the ids and--reason, oralerts tagwith the ids and--addor--removeper tag. - A status plan is stale when an alert's status changed or the alert no longer resolves. A tags plan is stale only when an alert no longer resolves. Both checks read through a search, so a change made within one index refresh may be missed.
cases_create_plan creates one case.
| Input | Value |
|---|---|
title |
Required, at most 160 bytes, without a line break |
description |
Optional, at most 4,096 bytes |
tags |
0 to 10 unique strings, each at most 256 bytes |
severity |
Optional: low, medium, high, or critical
|
cases_comment_plan adds one comment to a case.
| Input | Value |
|---|---|
id |
The case id, at most 1,024 bytes |
message |
At most 4,096 bytes |
cases_set_status_plan closes or reopens cases.
| Input | Value |
|---|---|
ids |
1 to 20 unique case ids, each at most 1,024 bytes |
status |
open or closed
|
- A new case has no assignees:
assigneesis an unknown input key. It is created withsettings.syncAlertsset tofalse, andsettingsandsyncAlertsare unknown input keys too. - A create plan shows the title on the action line. Its detail lines are
severity:,tags:, anddescription:with the full text, each when set, then the linesyncAlerts: false. - A comment plan's first detail line is
case_id: <case id>, then the full message. Case titles are not unique, so the id names the case. - A status plan shows
<id> <title> <from> -> <to>per case, oralready <status>, then the lineattached alerts: not changed (syncAlerts is off for every case listed). -
cli_equivalentiscases create --title <title>with--description,--tagper tag, and--severitywhen set;cases comment <id> --message <message>; orcases closeorcases openwith the ids. - A comment plan is stale when the case's title or status changed. Another
comment on the case does not make it stale. A status plan sends the case
versionit read; Kibana answers a changed case with 409, and the plan becomesstalewithplan_stale.
cases_set_status_plan refuses with case_sync_alerts when any case's
settings.syncAlerts is not the JSON value false: on, missing, or another
type. With alert sync on, Kibana also closes or reopens the alerts attached to
the case, and those alerts are not in the plan. No plan is stored and nothing
is written. The message is The case syncAlerts setting must be false.
Both drift checks repeat the test. If a case's syncAlerts is no longer
false at either check, the plan closes as stale and the call returns
case_sync_alerts without a write.
rules_create_plan creates one rule, always disabled. Its one input, rule,
is a JSON object of at most 65,536 bytes when serialized.
-
rule_id,name, andtypeare required non-blank strings. -
enabledmust be absent orfalse. The plan storesenabled: false, so the class cannot create an enabled rule. - These keys are refused:
id,created_at,created_by,updated_at,updated_by,revision,version, andexecution_summary. A non-emptyactionsorresponse_actionsis refused because it calls connectors or acts on hosts when the rule fires. A non-emptyexceptions_listis refused because its pointers are stack-specific and onlystate pushresolves them. - A
rule_idthat already exists iselastic_conflict, and no plan is stored. A rule with thatrule_idthat appears after planning makes the planstale, and so does a 409 answer to the write. - The form shows every field of the stored rule on its own line as
<key>: <JSON value>, whole: therule_idline first, then the other fields in byte order of the key. A query with line breaks or tabs shows them as\nand\t. A string with DEL, a C1 control, a Unicode line or paragraph separator, or a bidirectional control isinvalid_argument. - There is no separate query limit. A rule whose form text passes 8,192 bytes
is
plan_too_large. Create a larger rule withrules import. -
cli_equivalentisnull: no CLI command takes a rule inline. Userules importwith a file. - A response that shows another
rule_idor an enabled rule makes the planunknown, neverapplied.
The Note: line of a rule create names no credential:
Note: Kibana creates the rule disabled and without an API key. The credential that first enables it gives it a key, and the rule then runs with that credential's privileges.
The created rule has no API key while it stays disabled. Enabling it takes a
separate rules_set_enabled_plan with its own confirmation, or the CLI. The
credential that first enables it gives it its key.
An applied plan's outcome counts objects as follows. complete is true
when updated + unchanged equals requested and failed is 0.
| Kind | requested |
updated |
unchanged |
failed |
created |
|---|---|---|---|---|---|
rules_set_enabled |
Rules in the plan | Rules reported changed | 0 | Rules reported failed or skipped, plus rules not reported | null |
alerts_set_status, alerts_set_tags
|
Alerts in the plan | Alerts reported updated | Alerts reported unchanged | Alerts reported failed or in version conflict, plus alerts not reported | null |
cases_set_status |
Cases in the plan | Cases reported updated | Cases already in the requested status | Cases reported failed | null |
cases_comment |
1 | 1 | 0 | 0 | null |
cases_create |
1 | 1 | 0 | 0 | {"case_id": "<id>"} |
rules_create |
1 | 1 | 0 | 0 | {"rule_id": "<rule_id>"} |
| Kind | Set back by | Not restored |
|---|---|---|
rules_set_enabled |
The same tool with the opposite value | The API key of a rule that had none: it keeps the key of the credential that enabled it |
alerts_set_status |
The same tool with the earlier status | The workflow user, time, and reason |
alerts_set_tags |
A second plan that adds or removes the named tags | Prior membership. The plan does not record which tags an alert had, so adding a tag that was present and then removing it loses it |
cases_set_status |
The same tool with the opposite status | The close time and the closing user |
cases_comment |
Nothing in elasticctl removes a comment | The comment stays |
cases_create |
cases delete in the CLI |
Nothing once deleted |
rules_create |
rules delete in the CLI |
Nothing once deleted |
A create or a comment is sent once. If its answer is lost, the plan is
unknown, and planning again would add a second case or comment. Read the
case first.