MCP integration

Expose Polarity to Claude Code, Cursor, Codex, and any MCP client over the Model Context Protocol.

Polarity ships an MCP server that exposes its core operations as tools. Point your MCP client at it and your AI coding assistant can read traces, run experiments, query datasets, and create alerts on your behalf.

Install

The MCP server is bundled with the plr CLI. Once plr is on PATH:

plr mcp serve

It speaks MCP over stdio — point any MCP client at the command.

Claude Code

Add this to your Claude Code MCP config (~/.config/claude-code/mcp-servers.json or via claude mcp add):

{
  "polarity": {
    "command": "plr",
    "args": ["mcp", "serve"],
    "env": {
      "POLARITY_API_KEY": "plr_live_..."
    }
  }
}

See the Claude Code integration page for the full setup.

Cursor

In Cursor → Settings → MCP → Add server:

Name:    Polarity
Command: plr mcp serve
Env:     POLARITY_API_KEY=plr_live_...

See the Cursor integration page.

Codex

codex mcp add polarity plr mcp serve --env POLARITY_API_KEY=plr_live_...

What the MCP server exposes

Tool	What it does
`keystone_eval_run`	Upload a spec, create an experiment, run it, wait for completion, and return RunResults. Accepts `spec_path` or inline `spec_yaml`.
`keystone_eval_list`	List experiments visible to the API key.
`keystone_eval_get`	Get full RunResults (per-scenario invariants, costs, traces) for one experiment.
`keystone_eval_metrics`	Aggregate metrics for an experiment (pass rate, p95 wall, total cost, etc.).
`keystone_eval_compare`	Compare two experiments; returns metric deltas and a `regressed` flag.
`keystone_logs_traces`	Fetch trace events with optional filters (experiment, sandbox, agent, event type, tool, since). Capped output.
`keystone_logs_trace`	Fetch a single trace by ID — every span rooted at it.
`keystone_logs_spans`	Fetch spans matching a filter (by trace, root_span, tool, etc.).
`keystone_logs_scenarios`	Per-scenario rows for an experiment (filter by status to find failures).
`keystone_logs_scores`	Score rows for an experiment, optionally filtered by rule.

The exact tool list is discoverable — your MCP client can call tools/list to see what's available in the current SDK version.

Use cases

"Why did experiment X fail?" — assistant calls keystone_logs_scenarios (status=failed) then keystone_logs_traces to pull the spans.
"Run this spec and tell me if it passes" — assistant calls keystone_eval_run with inline spec_yaml.
"Compare last night's run to this morning's" — keystone_eval_compare with the two experiment IDs.
"What's the p95 latency on the latest experiment?" — keystone_eval_metrics.
"Pull the full trace for span xyz" — keystone_logs_trace with the root span id.

Treat the MCP server as a structured CLI for Polarity — eval + trace verbs surfaced as tools your coding assistant can call.

Polarity-as-MCP vs. Paragon-as-MCP

There are two separate MCP servers in the Polarity stack:

Server	Exposes	Run with
Polarity MCP (this page)	Experiments, traces, datasets, alerts	`plr mcp serve`
Paragon MCP (page)	The Paragon CLI itself (run a Paragon task from inside another assistant)	`paragon mcp-server`

They're complementary. Most teams install both.

OpenTelemetry Examples