---
title: Query history from your agent
description: >-
  Point Cursor or Claude Code at reeval mcp, so your coding agent can read runs,
  compare them and query lift itself.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

**Goal:** let the agent you code with answer "what regressed?" or "did the skill help?" from your reeval history, without you pasting output.

`reeval mcp` serves the history as read-only MCP tools. Your agent calls `compare`, `show`, `transcript` or `query_lift` and gets the JSON the CLI prints with `--json`, trimmed where it repeats itself: `compare` leaves out unchanged evals and `history` each run's eval tree, so long histories fit clients that blank a long tool result.

## Cursor

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "reeval": {
      "command": "npx",
      "args": [
        "reeval",
        "mcp",
        "--config",
        "${workspaceFolder}/reeval.config.ts"
      ]
    }
  }
}
```

`${workspaceFolder}` is the folder holding `.cursor/mcp.json`, so `reeval mcp` reads that project whatever directory Cursor starts it in. Enable the server under Customize; its tools then show as `reeval` tools in chat.

## Claude Code

```bash
claude mcp add --scope project reeval -- npx reeval mcp
```

`--scope project` writes `.mcp.json` at the project root, so everyone who clones the repository gets the server:

```json title=".mcp.json"
{
  "mcpServers": {
    "reeval": { "command": "npx", "args": ["reeval", "mcp"] }
  }
}
```

Claude Code starts it in the project root, where `reeval mcp` finds `reeval.config.ts`.

## Over HTTP

```bash
npx reeval mcp --http
```

```text
reeval mcp · acme · evals/.history/
  http://127.0.0.1:4986/mcp
Ctrl-C to stop.
```

Give the client the URL: `"url"` in `.cursor/mcp.json`, or `claude mcp add --transport http reeval http://127.0.0.1:4986/mcp`. It answers only on `127.0.0.1`, to local names and origins, with no token.

On a shared machine, or with the port reachable beyond it, set a token and send it as a header:

```bash
REEVAL_MCP_TOKEN=$(openssl rand -hex 32) npx reeval mcp --http
```

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "reeval": {
      "url": "http://127.0.0.1:4986/mcp",
      "headers": { "Authorization": "Bearer ${env:REEVAL_MCP_TOKEN}" }
    }
  }
}
```

## What the agent gets

Asked "which evals pass on the latest run?", an agent calls `query_eval_trend` with `{ "where": { "outcome": "pass" } }`:

```json
{
  "columns": ["eval_key", "run_id", "started_at", "branch", "pr_number", …],
  "rows": [
    {
      "eval_key": "evals/a.eval.ts › writes ok",
      "run_id": "20260928T064231Z_e404369_cursor-agent_xxa1",
      "outcome": "pass",
      "pass_at_1": 1,
      …
    }
  ],
  "truncated": false
}
```

The server's instructions tell it where to start: `failures` when a run failed, then `transcript`, `compare`, `history` and the `query_*` views. Every tool and resource is on the [reeval mcp](/reference/cli/mcp) page.

Claude Code defers MCP tools behind a tool search, so an agent that hasn't heard of reeval may never load them. A line in `AGENTS.md` or `CLAUDE.md` fixes that: "To debug a reeval run, use the `reeval` MCP server's `failures` tool first."

<Info>
  `reeval mcp` never runs evals. When the agent should run one, it runs `reeval run` in its terminal, behind your command approval.
</Info>

## Variations

| Variation | How |
|---|---|
| Another project | Pass `--config path/to/reeval.config.ts` |
| A narrower agent | Most clients let you turn tools off one by one; `failures`, `compare` and `transcript` cover a regression hunt |
| Unrecorded runs | `history` lists them when nothing is recorded, or with `all: true`; `failures`, `show`, `compare` and the queries already include scratch runs from `.reeval/runs` |

## Next

<CardGroup cols={2}>
  <Card title="reeval mcp" icon="plug" href="/reference/cli/mcp">
    Every tool, resource and security check.
  </Card>
  <Card title="History" icon="clock-rotate-left" href="/guide/history">
    Record runs so there's history to query.
  </Card>
</CardGroup>