MCP tools

You will learn the Cordo MCP tool catalogue.

Endpoint: https://<api-host>/mcp (streamable HTTP). Auth: Authorization: Bearer lxp_… (personal access token).

Tools

Tool	Purpose
`cordo_context`	Session primer: user, non-empty streams, views
`cordo_help`	Tool catalogue plus short investigation recipes
`describe_stream`	Stream metadata + learned field catalog
`top_values`	Top values for one field; optional `normalize_uri` and `time_basis`
`query`	Aggregates / search with filters, lookbacks, optional `time_basis`, optional complete-event `raw_search`, listed aliases (`level`, `severity`, `message`, …), optional compare, and freshness / truncation
`sample_events`	Matching samples; optional `time_basis`, `raw_search`, and `order_by` for top-N
`recent_events`	Raw Postgres ingest tail
`summarize_stream`	Volume + top values + samples in one call
`ops_digest`	Ops triage: volume, status/level, slow routes, failing jobs; with anomaly detection on, open finding counts and the top five open findings
`list_patterns`	Log patterns for a window: `relative` or `from` / `to`, `errors_only` or `level`, `service`, `q` (template text), `sort` (`count`, `change`, `first_seen`, `errors`). Structured patterns carry `kind: "structured"`
`get_trace`	Request timeline by `request_id` (or configured field)
`event_context`	Neighbours before/after one `event_id` (optional same-request correlate)
`manage_views`	Saved view list/get with `events:read`; create/update/delete with `views:write` (`visibility`: `private` or `stream`)
`resolve_view` / `tail_view`	Run or live-tail a view you can see
`manage_streams`	Stream list/get with `streams:read`; create/update/clear/delete with `streams:write` (including retention and visibility). `clear` keeps the stream and wipes events/learnings; requires `confirm=true` and `confirm_name` (exact stream name) after confirming with the user
`manage_stream_api_keys`	Bounded ingest key create / list / safe rotate / revoke, with optional protocol scopes and per-key event ceilings plus lifecycle health state
`ingest_events`	Write sample JSON events with `events:ingest` PAT permission and the Ingest keys stream role (prefer stream keys for production)

MCP ops_digest is product-scoped triage: it needs streams:read plus events:read and still follows stream access and token allowlists. The platform-wide ops:read scope applies only to REST /v1/ops/*; it does not unlock or broaden any MCP tool.

Detect tools

Tool	Purpose
`manage_metrics`	Recorded metric CRUD + series (`metric_id` UUID or name); includes recording health
`manage_monitors`	Detection monitor CRUD plus immutable history (`action: history`); includes evaluation health, `eval_offset`, `trigger_periods` / `recovery_periods`, and optional `recovery_value` (OK-side clear threshold while an alert is open)
`manage_channels`	Notification channel CRUD, test-fire, and attach to monitors; destinations are write-only and reads include sanitized delivery health
`manage_alerts`	List / get alerts and bounded evidence (`action: list` / `get` / `evidence`); `list` accepts `finding_id`

manage_metrics create and update accept anomaly_scan (default true) to include or exclude a metric from anomaly detection. manage_monitors creates a Findings monitor with source_type: "findings", condition_type: "finding", and a findings_filter (kinds, min_severity, services, pattern_ids) and optional findings_alert_mode (finding or incident).

When Cordo disables a metric or monitor itself (for example a stream clear removed the patterns it filters on), manage_metrics and manage_monitors return disabled_reason and health.detail explains it. The reason clears when you enable it again.

Concepts: Detect and alert. Web steps: Detect and alert.

Findings tools

Tool	Purpose
`list_findings`	Anomaly findings: `status` (`open` default, `resolved`, `dismissed`, `all`), `kind` and `severity` (comma lists), `service`, `pattern_id`, `relative` or `from` / `to`, `include_learning`, `limit`, `cursor`, optional `group_by=incident`. Items carry `headline`, `observed` / `baseline` / `deviation`, `reasons`, `incident_id`, and metric fields for Metric findings; `anomaly_detection` reports whether detection is on. `get_finding` includes `incident` and `siblings` when grouped
`get_finding`	One finding with reasons, timeline, evidence (`metric`, `step`, `window`, `sensitivity`, `z_threshold`, `unit`), up to 10 sample events, and `next_steps`
`manage_findings`	`dismiss` (`finding_id`, `reason`), `reopen`, `mute` (`pattern_id` / `service` / `kind`, `until` of `24h`, `7d`, or `never`, `note`), `unmute` (`mute_id`), `list_mutes`. Writes need `monitors:write` and the Settings stream role

Reading findings and patterns needs only streams:read and events:read. Kinds and thresholds: Anomaly detection. Recipe: Find what's unusual with an agent.

For manage_channels, webhook_url, email_to, and signing_secret are write-only inputs. Omit them on update to keep the stored values. List, get, create, and update results never return reusable destinations or secrets; Settings-role callers receive a non-reusable destination_display, while Query-role callers receive only channel identity, state, attachment references, and sanitized health. Create, update, delete, test, and monitor attachment actions require the Settings stream role or higher.

References

stream_id and view_id accept a UUID or name (case-insensitive) after context is loaded. Names are convenient while exploring; use UUIDs for durable automation and especially for writes.

If more than one accessible, PAT-allowed stream has the same name, Cordo returns ambiguous_stream before the tool reads or changes anything. Candidates contain only the stream UUID, name, and workspace UUID. Streams outside the token allowlist neither create ambiguity nor appear in the response. Retry with the intended UUID.

Sample ingest authorization

ingest_events is an agent convenience for sample data, not a production shipping path. The personal access token needs the events:ingest scope, the stream must be inside any token stream allowlist, and the token's user must currently hold the Ingest keys stream role or higher. Removing the user or lowering their role takes effect on the next call.

View visibility

manage_views create/update accept visibility: private (creator only) or stream (any member who can query the stream). The alias workspace maps to stream. New views default to private. List, resolve_view, and tail_view return only views the caller may open. Update and delete stay owner-only.

PAT stream allowlists constrain manage_streams and global manage_views inventories before pagination or saved sidebar order is applied. They also filter UUID/name resolution before Cordo decides whether a view reference is missing, unique, or ambiguous. Excluded rows therefore do not consume page slots, set has_more, create cursors, or appear in ambiguity candidates. An empty allowlist remains unrestricted within the token owner's current memberships.

For a cross-stream saved query, pass query.stream_ids including the home stream. Cordo requires current Query access and PAT allowlist access to every referenced stream before create, update, resolve, tail, or export work starts. When resolve_view or tail_view omits stream_id, the resolved home stream is checked too. Disallowed name matches are not included in ambiguity candidates, and one denied stream makes the whole operation return not found.

Concept: Views.

Stream visibility

manage_streams create/update accept visibility: private (invited people plus workspace owners/admins) or workspace (every workspace member can query). The older name team is still accepted on write and stored the same way. Responses and list/get only return private or workspace.

This is not the same as view visibility: manage_views still treats inbound workspace as an alias for stream (anyone who can query that stream). Stream workspace means every member of the stream’s workspace.

Concept: Accounts and security.

Typical flow: cordo_context → describe_stream → query / ops_digest, or list_findings for "what's unusual?".

Complete event text

query, sample_events, and saved view queries managed through manage_views accept:

{
  "raw_search": {
    "term": "downstream timeout",
    "mode": "literal"
  }
}

literal is a Unicode case-insensitive substring (3–256 characters). regex uses RE2 (1–256 characters) and is case-sensitive unless the pattern opts in. It searches complete stored JSON, including nested keys/values and non-string scalars. raw_search and learned-field filters combine with AND.

Inspect monitors and alerts

To answer "what has this monitor been doing, and what fired?":

manage_monitors action=list — check health.status (error / never_evaluated / ok) and health.evaluation (pending_open / firing / pending_resolve / cooldown).
manage_monitors action=history with monitor_id and either relative=1h|6h|24h|7d or from/to — read state/value samples, lifecycle events, and explicit unknown gaps. Pass group_hash for one grouped series; reuse next_cursor for the next page.
manage_alerts action=list with status=firing — note each id and its investigation_path.
manage_alerts action=evidence with alert_id — monitor snapshot, immutable fire/resolve values, and a bounded contributing-event sample.

Inspect findings

To answer "what's unusual right now?":

list_findings with status=open (add severity=critical for the worst).
get_finding with finding_id — timeline, evidence, and sample events.
event_context on a sample event_id, or query with pattern: {"ids": [<pattern_id>]} over a wider window.
Only after the user confirms: manage_findings dismiss or mute.

The full recipe: Find what's unusual with an agent.