The server provides read-only access to F6 XDR data for searching, counting, field discovery, and artifact browsing.
Search supported XDR sections (alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions) with field:value queries, wildcards, time filters, ordering, and pagination; empty queries return whole sections.
Count records in a section, optionally using a query filter.
Discover available search fields, filter options, and suggested real values for fields.
List host-collected artifacts by asset_id or machine_id, and inspect an artifact's internal files/folders one level at a time.
The exposed schema is read-only; it does not include download, write, mark-event, abort, or artifact-collection tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@F6 XDR MCP Server Show me critical unresolved alerts from the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP-сервер к платформе F6 XDR. Даёт ИИ-ассистенту доступ к алертам, инцидентам, письмам, файлам, хостам и журналу — поиском на языке запросов платформы.
Тул | Назначение |
| Поиск по секции; пустой запрос возвращает секцию целиком |
| Количество записей |
| Доступные поля поиска |
| Доступные значения фильтров |
| Реальные значения поля по префиксу |
| Артефакты, собранные с хостов: багрепорты, логи, конфиги, дампы |
| Файлы и папки внутри собранного артефакта |
| Скачать артефакт или его часть в локальную папку |
| Пользовательские артефакты: сохранённые в консоли списки путей и команд |
| Запустить сбор артефактов с хоста |
| Остановить сбор, который ещё идёт |
| Пометить объект: закрыть алерт, отметить ложное срабатывание |
Секции: alerts, incidents, emails, files, events, connections, assets,
modules, audit, applications, application_versions.
Первые семь тулов только читают. xdr_download_artifact пишет файлы на диск,
xdr_mark_event изменяет данные, а три тула сбора действуют на хостах; все они по
умолчанию выключены, см. раздел «Безопасность».
Related MCP server: F5 MCP Server
Нужен Python 3.10+ и персональный API-токен пользователя XDR.
{
"mcpServers": {
"xdr": {
"command": "uvx",
"args": ["xdr-mcp"],
"env": {
"XDR_BASE_URL": "https://<your-xdr-host>",
"XDR_API_KEY": "<token>"
}
}
}
}Этот блок подходит для Claude Desktop, Cursor и VS Code. Для Claude Code:
claude mcp add xdr \
-e XDR_BASE_URL=https://<your-xdr-host> -e XDR_API_KEY=<token> \
-- uvx xdr-mcpВместо uvx можно использовать pip install xdr-mcp и команду xdr-mcp, либо
контейнер — docker run -i --rm -e XDR_BASE_URL -e XDR_API_KEY ghcr.io/f6-security/xdr-mcp
(образ собран под linux/amd64 и linux/arm64).
Переменная | Назначение |
| Адрес вашей инсталляции XDR |
| Персональный API-токен пользователя |
|
|
|
|
|
|
| Папка, куда |
| PEM-бандл для инсталляции за внутренним УЦ |
alerts severity : "critical" AND resolved : "false"
alerts timestamp >= now-1d AND NOT false_positive : "true"
incidents closed : "false" AND timestamp >= now-30d
emails is_blocked : "true" AND timestamp >= now-1d
assets edr_active : "true"
applications vendor : "Microsoft Corporation"
audit success : "false" AND timestamp >= now-7dУсловия объединяются через AND, OR, NOT и группируются скобками. Время —
обычно поле timestamp, относительное (now-1d, now-6h) или абсолютное.
Какие поля доступны в секции, покажет xdr_get_mapping; в application_versions
для дат используются first_seen и last_seen.
В строковых значениях работает * в любой позиции: name : "VDI-5*",
file_name : "*.exe". Без него значение должно совпасть точно. Если запрос ничего не
вернул, а значение могло писаться иначе, точное написание подскажет
xdr_get_suggestions: платформа отвечает на несовпавшее значение нулём записей, а не
ошибкой.
applications возвращает программное обеспечение, а application_versions —
записи его версий на активах. Сначала найдите нужное ПО в applications, затем
используйте его uuid в поле software_id:
application_versions software_id : "<software_uuid>"
application_versions software_id : "<software_uuid>" AND version : "1.2.3"
application_versions asset : "<machine_id>" AND last_seen >= now-7dsoftware_id поддерживается поиском, хотя отсутствует в xdr_get_mapping.
Поле asset принимает machine_id или точный current_name, соответствующий
одному активу. Ответ включает version, uuid, ts_created, ts_updated
и сведения об активе, например machine_id и computer_name.
Для секции доступны все пять тулов, принимающих секцию. Пагинация использует page_size
и offset; сортировка — version, ts_created, ts_updated с необязательным
префиксом -. xdr_count считает записи версий на активах: одинаковая версия
на разных активах может встречаться несколько раз. Поле version имеет
show_suggestions=false, поэтому пустой список подсказок допустим.
Всё, что возвращают читающие тулы, попадает в контекст языковой модели: адреса и темы писем, имена файлов, хосты, журнал действий. Выдавайте серверу токен с минимально необходимыми правами.
xdr_mark_event создаёт матчер — правило, которое применяется ко всем объектам,
подходящим под выражение, и этим тулом не отменяется. Поэтому тул выключен по
умолчанию; включайте XDR_ALLOW_WRITE осознанно и не добавляйте его в
авто-подтверждение MCP-клиента.
Собранные артефакты — одни из самых чувствительных данных платформы: дампы памяти,
учётные данные, история команд. xdr_download_artifact кладёт их на диск, а модели
возвращает только путь и размер — содержимое в контекст не попадает. Тул включается,
только когда задана XDR_DOWNLOAD_DIR; выбирайте для неё папку с ограниченным
доступом. Для списка и скачивания токену нужны права на артефакты.
xdr_collect_artifacts запускает на хосте сбор с правами SYSTEM или root. Сбор
нагружает хост, а пользовательские артефакты могут нести команды, которые на нём
выполнятся. Поэтому тулы сбора включаются своей переменной XDR_ALLOW_COLLECT, а не
XDR_ALLOW_WRITE. Произвольных команд тул не принимает, только пользовательские
артефакты, сохранённые человеком в консоли. За вызов — один хост, массового запуска
нет. Пути проверяются до запроса: неподходящий путь роняет весь сбор. Для путей,
пользовательских артефактов, багрепорта, дампов памяти, истории команд и ещё
нескольких частей платформа просит одноразовый код, если у пользователя токена нет
списка разрешённых IP. С XDR_PASSWORD_PROMPT=1 сервер спрашивает его в отдельном
окне и отправляет прямо в консоль. Модель его не видит, а окно показывает, что и с
какого хоста собирается. Без этой переменной модель спросит код в чате. Остановить
можно только сбор, который ещё идёт: отмену завершённого платформа тоже принимает, и
его архив после этого не читается. Не добавляйте тулы сбора в авто-подтверждение
MCP-клиента.
Модель угроз и порядок сообщения об уязвимостях — SECURITY.md.
См. CONTRIBUTING.md.
Get the total count of records in an XDR section. Optionally filter by query to count matching records only. For application_versions this counts per-asset records, not distinct version strings.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query string using field:value syntax, e.g. 'resolved : "false" AND severity : "critical"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. A string value may contain * as a wildcard, in any position: name : "VDI-5*", file_name : "*.exe", domain : "*corp*". Without a wildcard a string value must match exactly. Numeric and date fields do not take wildcards. Call xdr_get_mapping for the fields a section accepts, xdr_get_filters for the values an enumerated field takes, and xdr_get_suggestions to look up the exact spelling of a value — a value outside the accepted set returns zero results rather than an error. Time filtering uses fields from xdr_get_mapping, typically timestamp, with relative (timestamp >= now-1d, now-6h) or absolute values (timestamp >= "2024-01-01T00:00:00.000+03:00"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the "applications" section, filter by asset, e.g. (asset: "<machine_id>"). The "application_versions" section returns per-asset software version records. Filter by software_id: "<uuid from applications>" (supported even though absent from mapping), version: "1.2.3", or asset: "<machine_id or exact current_name>" identifying a single asset. For dates in this section use first_seen or last_seen, e.g. last_seen >= now-7d; ordering uses version, ts_created or ts_updated. A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for. (optional) | |
| section | Yes | Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds a genuinely useful semantic caveat that application_versions counts per-asset records rather than distinct version strings, preventing a real misinterpretation of the returned number, though it says nothing about cost or performance on large sections.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action, then the filtering option, then the one non-obvious caveat. No wasted wording and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description is nearly complete; the schema carries all query syntax detail. The only mild gap is that it does not state the shape of the returned count (bare number vs object), though 'total count' strongly implies a scalar.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the query parameter is documented in exceptional depth in the schema itself. The description only restates that query optionally filters the count and adds the application_versions counting caveat, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — get the total count of records in an XDR section — and clarifies the scope of the optional query filter. It distinguishes the count intent from the listing/search siblings implicitly rather than by naming xdr_search, so it is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when to use it (to obtain a total rather than records) and notes that the query can be omitted to count the whole section. It does not state when to prefer this over xdr_search or mention any preconditions such as calling xdr_get_mapping first, so guidance remains implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the files and folders inside a collected artifact, one level at a time, with their sizes. Takes the artifact's numeric 'id' from xdr_list_artifacts and an optional folder inside it (e.g. /var/log). Use it to find the part worth downloading rather than fetching a whole artifact.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Folder inside the artifact; omit for the top | |
| report_id | Yes | Numeric artifact id ('id' in xdr_list_artifacts) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description instead contributes the non-obvious behavior that listing is non-recursive ('one level at a time') and that sizes are returned. It does not say what happens with an invalid path or whether there is a result cap, but the key calling behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the tool does, followed by the prerequisite and the intended use. No filler or restatement of structured fields beyond what is needed for context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description covers the source of the required id, the meaning and default of the path, the granularity of results, and the return contents (names and sizes). Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are already documented there, including the 'id in xdr_list_artifacts' cross-reference. The description repeats that mapping and adds only a '/var/log' example, so it adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the files and folders inside a collected artifact') and immediately bounds the scope with 'one level at a time, with their sizes'. It also names the sibling that produces the required id, so an agent can distinguish it from xdr_list_artifacts without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete decision rule: use it to 'find the part worth downloading rather than fetching a whole artifact', which frames it as a cheaper precursor to a download step, and tells the agent the id must come from xdr_list_artifacts. It does not state an explicit when-not-to-use case or a sibling alternative for other browsing needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available filter options for an XDR section.
| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes | Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the result is a set of available filter options (metadata, not records), but says nothing about result shape, whether options are static per section, or whether they reflect live tenant state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. It is efficient, though the brevity leaves gaps that other dimensions penalize.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity, one-parameter discovery tool, so the description is close to sufficient for correct invocation. However, with no output schema, an agent gets no hint about the shape of the returned filter options, which is the main thing missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'section' parameter carries a full enum with a matching description, so the schema does the work. The description adds no meaning beyond that, such as how section choice changes the returned option set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get') and resource ('available filter options for an XDR section'), so an agent can tell it retrieves filter metadata rather than data. It does not differentiate itself from siblings such as xdr_get_suggestions or xdr_get_mapping, which could plausibly return similar-looking option lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisite (e.g., call before xdr_search to discover valid filter values), and no mention of when to prefer xdr_get_suggestions or xdr_get_mapping instead. The usage is only inferable from the phrase 'filter options'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available search fields for an XDR section. Returns field names, labels, categories, and supported operators. Call this first to understand what you can search on.
| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes | Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already establish the safety profile, so the description's real contribution is disclosing the return shape (field names, labels, categories, supported operators), which is valuable given there is no output schema. It omits any note on result size or pagination, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero padding, with the core verb and resource front-loaded and the return contents plus the usage cue following in priority order. Every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only discovery tool with no output schema, the description covers purpose, output contents, and invocation timing, which is nearly everything an agent needs. A brief mention of the section enum's practical meaning would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'section' parameter is a fully enumerated string, so the schema already carries the parameter meaning. The description adds no extra semantics about what each section contains or how to choose one, which is the expected baseline-3 outcome when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Get all available search fields for an XDR section', and it enumerates the returned content (field names, labels, categories, supported operators). It is clearly a metadata/schema-discovery tool, though it does not explicitly differentiate itself from the similarly named sibling xdr_get_filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call this first to understand what you can search on' gives a concrete sequencing instruction, positioning it as a prerequisite before searching. It stops short of naming alternatives or when-not-to-use cases, so it falls just under the explicit routing bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up real values of a field, optionally narrowed by a prefix. Use it when a query returns nothing and the value may simply be spelled differently — an unmatched value is answered with zero records rather than an error, so a guess is indistinguishable from a genuine absence. Each entry has a value to put in a query and a label for display; search on the value. Returns up to about ten entries, so narrow the prefix to see more. Field names come from xdr_get_mapping, where the ones worth asking about carry show_suggestions; an unknown field name comes back empty rather than as an error.
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | Field to list values of, as named by xdr_get_mapping | |
| prefix | No | Return only values starting with this. Omit for the field's first values. | |
| section | Yes | Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond them — zero-record responses instead of errors for unmatched values and unknown fields, roughly ten-entry result caps, and the need to narrow the prefix to page further. It also explains the value/label pair structure of each entry, which matters for correct follow-up queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with purpose and rationale, with no filler. The closing clause about unknown field names returning empty is a minor restatement of the earlier zero-records point, which slightly dilutes the ending.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description covers the return shape (value plus label), result volume, and pagination approach. Combined with fully documented parameters and explicit failure semantics, an agent has everything needed to call it and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by framing prefix as the mechanism for both narrowing and pagination past the ten-entry cap, and by tying field to xdr_get_mapping's show_suggestions marker. The section parameter is left entirely to the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('look up real values of a field') plus the optional narrowing behavior. It is clearly distinguished from siblings: field names come from xdr_get_mapping, and this tool resolves values rather than searching records. An agent can tell what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit triggering condition ('when a query returns nothing and the value may simply be spelled differently') and explains why guessing is unsafe, since an unmatched value returns zero records rather than an error. It also routes the agent to xdr_get_mapping for field discovery and notes to search on the value, not the label.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List artifacts collected from hosts — what an analyst gathered through the asset's Response → Artifacts: bug reports, logs, configs, memory dumps. Filter by host with asset_id (the asset's numeric id) or machine_id; with neither, lists artifacts across all hosts. Newest first by default. Each row has 'id' (for xdr_get_artifact_structure), 'internal_id' (for xdr_download_artifact), 'parts' (what was collected), 'command_status' (New, Queued, Pending, Uploading, Uploaded, Done, Failed, Aborted) and 'size' in bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number | |
| asset_id | No | Numeric asset id | |
| ordering | No | By creation time; default -ts_created (newest first) | |
| page_size | No | Rows per page (1-200, default 20) | |
| machine_id | No | Agent machine id (UUID); looked up to the asset id first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real behavioral context beyond that — unqualified calls fan out across all hosts, results are newest-first by default, and each row exposes command_status lifecycle values (New through Aborted) plus size in bytes. It omits total-count/pagination behavior and any permission prerequisites, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and dense: scope first, filtering semantics second, return shape last. The status enumeration (New, Queued, Pending, ...) is somewhat list-heavy but earns its place by telling the agent how to interpret command_status. No filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does so by naming the row fields an agent needs (id, internal_id, parts, command_status, size). Combined with annotations covering read-only safety and the schema covering pagination and ordering, an agent has enough to call this correctly without trial and error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds the combination semantics the schema cannot express: asset_id and machine_id are alternatives, and supplying neither changes the result set to all hosts. It also flags that the two id fields serve different downstream purposes, which clarifies which identifier to carry forward.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List artifacts collected from hosts") and immediately grounds it with concrete examples (bug reports, logs, configs, memory dumps). It also differentiates from siblings by naming the follow-up consumers of its id fields (xdr_get_artifact_structure, xdr_download_artifact), so an agent knows this is the entry point of a workflow rather than a duplicate of xdr_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the two scoping modes clearly: filter by host via asset_id or machine_id, or omit both to sweep across all hosts, plus the default ordering (newest first). It routes to the correct downstream tools via the id/internal_id fields. It does not explicitly exclude or contrast with xdr_search for text-based artifact lookup, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for events/objects in an XDR section. Returns matching records; an empty query returns the section unfiltered. Use xdr_get_mapping first to discover available fields.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string using field:value syntax, e.g. 'resolved : "false" AND severity : "critical"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. A string value may contain * as a wildcard, in any position: name : "VDI-5*", file_name : "*.exe", domain : "*corp*". Without a wildcard a string value must match exactly. Numeric and date fields do not take wildcards. Call xdr_get_mapping for the fields a section accepts, xdr_get_filters for the values an enumerated field takes, and xdr_get_suggestions to look up the exact spelling of a value — a value outside the accepted set returns zero results rather than an error. Time filtering uses fields from xdr_get_mapping, typically timestamp, with relative (timestamp >= now-1d, now-6h) or absolute values (timestamp >= "2024-01-01T00:00:00.000+03:00"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the "applications" section, filter by asset, e.g. (asset: "<machine_id>"). The "application_versions" section returns per-asset software version records. Filter by software_id: "<uuid from applications>" (supported even though absent from mapping), version: "1.2.3", or asset: "<machine_id or exact current_name>" identifying a single asset. For dates in this section use first_seen or last_seen, e.g. last_seen >= now-7d; ordering uses version, ts_created or ts_updated. A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for. | |
| offset | No | Number of results to skip. For the "modules" section the API pages in fixed steps, so offset must be a multiple of page_size there. | |
| section | Yes | Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions | |
| ordering | No | Sort field with optional - prefix for descending, e.g. -created_at (newest first). An unknown field is silently ignored: the API reports no error and the results come back in some other order, so use only the fields listed here. Per section — alerts: created_at, last_event, last_updated, severity; incidents: created_at, updated_at; emails: ts_created, delay; files: ts_created, delay; events: Header.Timestamp; connections: ts_parsed, ts_last_usage_parsed, service_count, duration; assets: last_activity, first_activity; modules: ts_created, name; audit: timestamp; applications: name, ts_created, ts_updated; application_versions: version, ts_created, ts_updated. | |
| page_size | No | Number of results per page (1-200, default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The definition goes beyond that with non-obvious behaviors: an empty query returns the section unfiltered and may be very large, an unparseable query is silently treated as free text rather than rejected, and an unknown ordering field is silently ignored — all important silent-failure disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose, then return behavior, then the prerequisite call. Nothing is redundant or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, 11-section search tool, the definition covers purpose, return shape, empty-query semantics, and the discovery path through xdr_get_mapping/xdr_get_filters/xdr_get_suggestions. With no output schema, a brief note on what a result record looks like would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in detail, including query syntax, per-section ordering fields, and the modules offset constraint. The top-level description adds no parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: search for events/objects within an XDR section, returning matching records. It names the sibling it depends on (xdr_get_mapping) but does not explicitly distinguish itself from xdr_count, which an agent could reasonably confuse with this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: call xdr_get_mapping first to learn the fields, and pass an empty query only when the whole section is intentionally wanted. The schema text further routes to xdr_get_filters and xdr_get_suggestions, but no explanation of when to prefer xdr_count over a search is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0xdr_count3 fields changedInput schema / properties / query / descriptionPrevious value: -"Search query string using field:value syntax, e.g. 'resolved : \"false\" AND severity : \"critical\"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. Call xdr_get_mapping for the fields a section accepts, and xdr_get_filters for the values an enumerated field takes — a value outside that set returns zero results rather than an error. Time filtering uses the timestamp field, relative (timestamp >= now-1d, now-6h) or absolute (timestamp >= \"2024-01-01T00:00:00.000+03:00\"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the \"applications\" section, filter by asset, e.g. (asset: \"<machine_id>\"). A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for. (optional)"New value: +"Search query string using field:value syntax, e.g. 'resolved : \"false\" AND severity : \"critical\"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. A string value may contain * as a wildcard, in any position: name : \"VDI-5*\", file_name : \"*.exe\", domain : \"*corp*\". Without a wildcard a string value must match exactly. Numeric and date fields do not take wildcards. Call xdr_get_mapping for the fields a section accepts, xdr_get_filters for the values an enumerated field takes, and xdr_get_suggestions to look up the exact spelling of a value — a value outside the accepted set returns zero results rather than an error. Time filtering uses fields from xdr_get_mapping, typically timestamp, with relative (timestamp >= now-1d, now-6h) or absolute values (timestamp >= \"2024-01-01T00:00:00.000+03:00\"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the \"applications\" section, filter by asset, e.g. (asset: \"<machine_id>\"). The \"application_versions\" section returns per-asset software version records. Filter by software_id: \"<uuid from applications>\" (supported even though absent from mapping), version: \"1.2.3\", or asset: \"<machine_id or exact current_name>\" identifying a single asset. For dates in this section use first_seen or last_seen, e.g. last_seen >= now-7d; ordering uses version, ts_created or ts_updated. A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for. (optional)"Input schema / properties / section / descriptionPrevious value: -"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications"New value: +"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions"Input schema / properties / section / enumPrevious value: -[
- "alerts",
- "incidents",
- "emails",
- "files",
- "events",
- "connections",
- "assets",
- "modules",
- "audit",
- "applications"
-]New value: +[
+ "alerts",
+ "incidents",
+ "emails",
+ "files",
+ "events",
+ "connections",
+ "assets",
+ "modules",
+ "audit",
+ "applications",
+ "application_versions"
+]xdr_get_artifact_structurexdr_get_filters2 fields changedInput schema / properties / section / descriptionPrevious value: -"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications"New value: +"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions"Input schema / properties / section / enumPrevious value: -[
- "alerts",
- "incidents",
- "emails",
- "files",
- "events",
- "connections",
- "assets",
- "modules",
- "audit",
- "applications"
-]New value: +[
+ "alerts",
+ "incidents",
+ "emails",
+ "files",
+ "events",
+ "connections",
+ "assets",
+ "modules",
+ "audit",
+ "applications",
+ "application_versions"
+]xdr_get_mapping2 fields changedInput schema / properties / section / descriptionPrevious value: -"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications"New value: +"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions"Input schema / properties / section / enumPrevious value: -[
- "alerts",
- "incidents",
- "emails",
- "files",
- "events",
- "connections",
- "assets",
- "modules",
- "audit",
- "applications"
-]New value: +[
+ "alerts",
+ "incidents",
+ "emails",
+ "files",
+ "events",
+ "connections",
+ "assets",
+ "modules",
+ "audit",
+ "applications",
+ "application_versions"
+]xdr_get_suggestionsxdr_list_artifactsxdr_search4 fields changedInput schema / properties / ordering / descriptionPrevious value: -"Sort field with optional - prefix for descending, e.g. -created_at (newest first). An unknown field is silently ignored: the API reports no error and the results come back in some other order, so use only the fields listed here. Per section — alerts: created_at, last_event, last_updated, severity; incidents: created_at, updated_at; emails: ts_created, delay; files: ts_created, delay; events: Header.Timestamp; connections: ts_parsed, ts_last_usage_parsed, service_count, duration; assets: last_activity, first_activity; modules: ts_created, name; audit: timestamp; applications: name, ts_created, ts_updated."New value: +"Sort field with optional - prefix for descending, e.g. -created_at (newest first). An unknown field is silently ignored: the API reports no error and the results come back in some other order, so use only the fields listed here. Per section — alerts: created_at, last_event, last_updated, severity; incidents: created_at, updated_at; emails: ts_created, delay; files: ts_created, delay; events: Header.Timestamp; connections: ts_parsed, ts_last_usage_parsed, service_count, duration; assets: last_activity, first_activity; modules: ts_created, name; audit: timestamp; applications: name, ts_created, ts_updated; application_versions: version, ts_created, ts_updated."Input schema / properties / query / descriptionPrevious value: -"Search query string using field:value syntax, e.g. 'resolved : \"false\" AND severity : \"critical\"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. Call xdr_get_mapping for the fields a section accepts, and xdr_get_filters for the values an enumerated field takes — a value outside that set returns zero results rather than an error. Time filtering uses the timestamp field, relative (timestamp >= now-1d, now-6h) or absolute (timestamp >= \"2024-01-01T00:00:00.000+03:00\"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the \"applications\" section, filter by asset, e.g. (asset: \"<machine_id>\"). A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for."New value: +"Search query string using field:value syntax, e.g. 'resolved : \"false\" AND severity : \"critical\"'. Pass an empty string to list the whole section unfiltered — deliberately, since that can be a very large number of records. Fields can be combined with AND, OR, AND NOT, OR NOT and grouped with parentheses. A string value may contain * as a wildcard, in any position: name : \"VDI-5*\", file_name : \"*.exe\", domain : \"*corp*\". Without a wildcard a string value must match exactly. Numeric and date fields do not take wildcards. Call xdr_get_mapping for the fields a section accepts, xdr_get_filters for the values an enumerated field takes, and xdr_get_suggestions to look up the exact spelling of a value — a value outside the accepted set returns zero results rather than an error. Time filtering uses fields from xdr_get_mapping, typically timestamp, with relative (timestamp >= now-1d, now-6h) or absolute values (timestamp >= \"2024-01-01T00:00:00.000+03:00\"). The calendar-rounding forms now/d, now/w and now/M return nothing, so use now-1d and the like. Note that timestamp is a search field: the ordering parameter takes an entirely different set of names. For the \"applications\" section, filter by asset, e.g. (asset: \"<machine_id>\"). The \"application_versions\" section returns per-asset software version records. Filter by software_id: \"<uuid from applications>\" (supported even though absent from mapping), version: \"1.2.3\", or asset: \"<machine_id or exact current_name>\" identifying a single asset. For dates in this section use first_seen or last_seen, e.g. last_seen >= now-7d; ordering uses version, ts_created or ts_updated. A query the API cannot parse is not rejected — it is treated as free text, so verify that the results match what you asked for."Input schema / properties / section / descriptionPrevious value: -"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications"New value: +"Section name, one of: alerts, incidents, emails, files, events, connections, assets, modules, audit, applications, application_versions"Input schema / properties / section / enumPrevious value: -[
- "alerts",
- "incidents",
- "emails",
- "files",
- "events",
- "connections",
- "assets",
- "modules",
- "audit",
- "applications"
-]New value: +[
+ "alerts",
+ "incidents",
+ "emails",
+ "files",
+ "events",
+ "connections",
+ "assets",
+ "modules",
+ "audit",
+ "applications",
+ "application_versions"
+]v0.1.0xdr_countxdr_get_filtersxdr_get_mappingxdr_searchScored across 7 tools
The search/count pair and the artifact tools are clearly distinct, but the metadata trio — xdr_get_mapping, xdr_get_filters, and xdr_get_suggestions — have overlapping purposes (all answer 'what can I search/filter on?'), and xdr_get_filters has a one-line description that gives no guidance on when to use it instead of get_mapping. xdr_get_suggestions and xdr_search could also be confused since both can return matching values.
All tools share the xdr_ prefix and snake_case, with a clear verb-first structure (search, count, get_*, list_*). The only deviation is that xdr_search and xdr_count drop the noun compared to the get_/list_ tools, which is minor and still readable.
Seven tools is a well-scoped set for a search-and-inspect server: one per query primitive plus two for the artifact workflow. Each tool has a distinct role, and nothing feels padded or missing from the count itself.
xdr_list_artifacts explicitly tells the agent to use its 'internal_id' with xdr_download_artifact, but no such tool exists in this set — the artifact workflow dead-ends after inspecting structure. There is also no way to perform response/containment actions or export search results, leaving the core lifecycle incomplete.
SOAR security playbooks for AI agents: fetch, full-text search, and count. Metered via Stripe.
Search log events, investigate anomalies, and manage cases in your Knowledge Grid tenant.
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
