invariance-mcp: Instructions file for Codex

AGENTS.md

Instructions for AI agents (Claude Desktop, Cursor, Claude Code, and any MCP client) on the tools @invariance/mcp exposes and how to use them against the Invariance observability platform.

What this server does

@invariance/mcp is an MCP server that gives an AI client direct, structured access to Invariance: it can query runs, nodes, monitors, signals, findings, reviews, cases, workflows, divergences, guardrails, receipts, and saved views, and can record traces and evidence — all as tool calls, without leaving the conversation. Tool names follow invariance_<resource>_<action>.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) so you can tell inspection tools from state-changing ones without reading the prose description. For complex object arguments, tools take JSON-encoded strings which the server parses before calling the API.

Setup (one-time, human-assisted)

A human configures the server in the MCP client (Claude Desktop / Cursor / Claude Code) with an INVARIANCE_API_KEY. See README.md for client config snippets. Agents should prompt the user to do this rather than attempt it themselves.

Call invariance_doctor first when you connect — it verifies server + API + auth health before you issue other calls.

Auth model

• Reads accept an agent or operator key.
• Receipts writes (invariance_receipt_create, invariance_receipt_batch) require an agent API key — operator tokens get a 403. All other writes work with either key.

Tools by domain

Core trace loop

• invariance_run_start / _get / _list / _finish / _fail / _verify — wrap a task in a run (read/write).
• invariance_node_write / _list — record tool/LLM/decision/observation nodes (read/write).
• invariance_run_inspect, _operational_graph, _llm_calls, _node_types, _metrics, _fork — triage views over a run (read; _fork writes).

Observability and detection

• invariance_monitor_* — create/evaluate predicates over nodes/runs; pause/resume/executions/findings.
• invariance_signal_* — emit/list/get/acknowledge/resolve.
• invariance_finding_* — list/get/update (status: open | review_requested | resolved | dismissed).
• invariance_review_* — list/get/claim/unclaim/resolve.
• invariance_divergence_list / _get (read), invariance_divergence_update (write) — expected-vs-observed gaps; transition status to open | accepted | dismissed | converted_to_monitor.