Skip to content

Find what's unusual with an agent

You will learn how an agent connected over MCP can answer "what's unusual right now?" from a stream's findings and patterns, and when it may act on them.

This recipe uses the same findings as the Findings page. Turn on anomaly detection for the stream first, and connect MCP.

What the agent needs

To Personal access token scopes Stream role
Read findings and patterns streams:read, events:read Query
Dismiss, reopen, or mute findings add monitors:write Settings
Create a Findings monitor add monitors:write Settings

A read-only token is enough for the investigation. Only add monitors:write when you want the agent to change things.

Ask it

Try prompts such as:

  • What's unusual on checkout-api right now?
  • Anything critical on payments in the last day?
  • Why did the error rate on billing jump?

The steps the agent follows

  1. list_findings with status: "open" — add severity: "critical" to start with the worst, or group_by: "incident" to nest co-firing findings. Each item has a headline, observed against baseline, deviation, reasons, and incident_id when grouped. get_finding returns siblings in the same incident. If anomaly_detection.enabled is false, detection is off for the stream.

    { "stream_id": "checkout-api", "status": "open", "severity": "critical" }

  2. get_finding with finding_id — the timeline, the evidence window and values, and up to 10 sample events, plus suggested next_steps.

  3. event_context on a sample event_id — what happened just before and after.
  4. list_patterns and query with pattern: {"ids": [<pattern_id>]} — how the pattern behaves over a wider window or grouped by another field.
  5. For a Metric finding, manage_metrics with action: "series" and the finding's metric_id around the window — every group of the metric, not just the one that moved.
  6. Only after you confirm, manage_findings:
  7. dismiss with finding_id and a reason (for example expected, noise, or fixed);
  8. mute with pattern_id, service, or kind, and until of 24h, 7d, or never. A mute also dismisses the matching open findings;

  9. reopen, unmute, or list_mutes.

    { "action": "dismiss", "stream_id": "checkout-api", "finding_id": "…", "reason": "expected" }

To stop one noisy metric being scanned, the agent can call manage_metrics with action: "update" and anomaly_scan: false.

Other useful calls

  • list_findings filters by kind and severity (comma lists), service, pattern_id, and relative or from / to; include_learning adds learning-period findings. Results carry a summary of counts by status, kind, and severity.
  • list_patterns sorts by count, change, first_seen, or errors, with errors_only, level, service, and q (template text) filters. Use sort: "change" for "what got louder?".
  • ops_digest adds an open_findings summary and the top five open findings when detection is on.
  • manage_monitors with source_type: "findings", condition_type: "finding", and a findings_filter (kinds, min_severity, services, pattern_ids) creates a Findings monitor. manage_alerts list accepts finding_id.

Keep the agent safe

Event text, pattern templates, and finding headlines come from your logs, so treat them as untrusted. Cordo labels every tool result that way and marks manage_findings and manage_monitors as write tools; your MCP client can require approval before it calls them.

Next