MCP Server

Hand a recording to an LLM client over the Model Context Protocol. The agent describes it, queries it with PromQL, looks for anomalies and bottlenecks, and writes what it found back into the recording as timeline events you see in the viewer.

Version note

The six read tools are in every current release. The write tools (add_event, run_checks, export_query, viewer_link, remove_events) and the server flags that go with them arrive in Rezolus 6.0 and are not in any 5.x release. rezolus mcp install is in 5.23.1 and later, without the server flags on 5.x. Check with rezolus mcp --help.

Setup

One command registers the server with Claude Code and installs the rezolus-mcp skill, which tells the client how to investigate a recording: describe it and its metrics before querying, extract features before forming hypotheses, and pick one recording out of a multi-recording archive.

# Register for every project (user scope) and install the skill

$rezolus mcp install

# This project only, with exports enabled (the directory must exist)

$mkdir -p "$PWD/exports"

$rezolus mcp install --scope project --export-dir "$PWD/exports"

# Show what would change, change nothing

$rezolus mcp install --dry-run

In Claude Code, /mcp lists the server and /rezolus-mcp loads the skill; claude mcp list checks the connection from a shell. Re-running replaces the entry, which is how server flags are changed. If another scope already has a rezolus entry that would win, install says so and prints the command that removes it.

Registration runs claude mcp add, so claude needs to be on PATH. Without it, project scope writes .mcp.json directly and user scope prints the command to run. A project-scope server is approved in Claude Code the first time it opens in that directory. Give --export-dir an absolute path: the registered command is started from whatever directory Claude Code is in.

Other MCP clients start the server the same way: a stdio command of rezolus mcp plus any of the server flags.

Tools

Every tool that reads a recording takes its path (.parquet, .rez or .dendro, detected by content). On a .rez holding several recordings, a recording selector such as {"source": "redis"} picks one. describe_recording without a selector lists the recordings and the selector for each; run_checks without one evaluates every recording; the other tools refuse an archive when no single recording is named, and list the choices. Tools come in three tiers, decided by what a call can destroy.

Read

Tool	What it returns
`describe_recording`	Source, agent version, time range; for an archive, its recordings and the selector for each
`describe_metrics`	Every metric with its type, labels and help text
`extract_features`	A versioned overview record: per-metric stats, noise class, anomalies, regime shifts, correlations, resource rankings. Needs at least 10 seconds of data
`query`	A PromQL result; `rate()` values carry an uncertainty band from the acquisition window
`detect_anomalies`	MAD, CUSUM and FFT findings for the one series its query produces (the one-shot CLI form can also sweep every metric)
`analyze_correlation`	How two series move together over the recording

Additive (always on; Rezolus 6.0 and later)

None of these removes anything from a recording. add_event and run_checks add events (a check verdict replaces the stored verdict with the same id, so a re-run updates it); export_query and viewer_link leave the recording untouched.

Tool	What it does
`add_event`	Marks an instant or a range with a kind, a description and the evidence; the viewer draws it on the timeline. Returns the event id
`run_checks`	Evaluates the recording's KPI checks and returns each verdict with its violation windows; `annotate: true` writes them as events
`export_query`	Writes a range query as CSV or parquet (series, timestamp, value, lo, hi) under `--export-dir`, for analysis outside PromQL. Refuses every call when the server has no export directory
`viewer_link`	A link that opens a running `rezolus view` at a section or chart, a time range and the rest of the view state. A full URL needs the viewer's address, from `--viewer-url` or the call's `viewer_url`

Mutating (off unless enabled; Rezolus 6.0 and later)

Tool	What it does
`remove_events`	Removes events by id, kind and/or source (`source: "mcp"` removes everything an agent wrote). Needs `--allow-mutating`; without it the tool is neither listed nor callable

Each read tool also runs one-shot from a shell with the same analysis, e.g. rezolus mcp query out.rez 'sum(rate(cpu_cycles[1m]))'; see the CLI reference.

Workflow

The skill carries this; for a client without it, the same steps apply.

describe_recording, then describe_metrics: metric names come from the recording, not from memory.
extract_features for the overview before forming hypotheses.
query, detect_anomalies and analyze_correlation to test them. A check or an anomaly search needs one series, so aggregate with sum() or add label matchers.
add_event for what was found, with the query and values in its details, and viewer_link to hand the person the chart.

Report an absent metric as missing. A sampler that was off, or a kernel without the hook, leaves it out of the recording.
Compare rate() values against their uncertainty band; a change smaller than the band was not measured.
Report a correlation as two series moving together, without a claim about which one drives the other.

Server flags

Set when the server starts; install accepts the same flags and bakes them into the registered command. These flags control the write tools and arrive with them in Rezolus 6.0.

Flag	Effect
`--allow-mutating`	Enables `remove_events`
`--export-dir DIR`	Where `export_query` may write; must exist, and should be absolute. Files land under a bare name, never over an existing file; a result over a million rows is refused. Without it the tool refuses every call
`--viewer-url URL`	A running viewer's address, so `viewer_link` returns full URLs. `rezolus view` picks a random port unless started with `--listen`, so pin one, e.g. `rezolus view --listen 127.0.0.1:4200 out.rez`

# Run the stdio server by hand with all three flags

$rezolus mcp --allow-mutating --export-dir "$PWD/exports" --viewer-url http://127.0.0.1:4200

← Usage Architecture →