--- title: History MCP server description: >- reeval mcp serves a project's run history to an agent as MCP tools and resources. --- > ## 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. `reeval mcp` is a read-only MCP server for the loaded project's run history. Its name is `reeval` and its title is `reeval run history`. Stdio is the default. Closing stdin ends the stdio server, and `SIGINT` or `SIGTERM` ends either server with exit code 0. Tools set `readOnlyHint` and `idempotentHint` to true, and `destructiveHint` and `openWorldHint` to false. Tool results and resource bodies replace secrets with `[REDACTED]`. Errors return the redacted message. A run reference is `latest` (the default), `latest~N`, a run id, a unique prefix, or a Git SHA prefix of 4 to 40 hexadecimal characters. The SHA match ignores case and selects the newest run. A run id prefix must be unique. No match is an error. Recorded runs and scratch runs both resolve. For more information about connecting an MCP client, see [CLI reference](/reference/cli#reeval-mcp). For more information about MCP servers an evaluation gives its harness, see [Connect MCP servers](/configuration/environments/mcp-servers). ## `--http` `--http` serves stateless Streamable HTTP at `POST /mcp`, a fresh server per request. Other methods on `/mcp` return 405, and other paths return 404. `--port`, `--host`, and `--token` require `--http`, or they exit with code 2. ## `--port` `--port` sets the TCP port (default 4986). The value is an integer from 1 to 65535. Any other value, or a port in use, exits with code 2. ## `--host` `--host` sets the bind address (default `127.0.0.1`). A host other than `127.0.0.1`, `localhost`, or `::1` prints a warning. The `Host` header must be `127.0.0.1:`, `localhost:`, `[::1]:`, or the bind address with the port. A sent `Origin` must be `http://` plus one of those values, or the response is 403. ## `--token` `--token` is the bearer token on `Authorization: Bearer`. An empty `--token` value exits with code 2. An empty `REEVAL_MCP_TOKEN` value is treated as absent. When the flag is absent, the token is `REEVAL_MCP_TOKEN`. When both are absent, requests need no token. A missing or different token returns 401 with `WWW-Authenticate: Bearer`. ## `failures` The `failures` tool returns `fail` and `infra_error` attempts for a run reference. `filter` keeps evaluations whose id contains the string, ignoring case. `limit` defaults to 10 (1 to 100), and `tail` defaults to 12 (0 to 100). Cells include `new`, `failingSince`, and `lastPass`. `note` is set when nothing failed, and `next` when something did. ## `history` The `history` tool, titled **Run history**, returns one row per evaluation, oldest run first. `filter` keeps evaluations whose id contains the string, ignoring case. `limit` defaults to 20 (1 to 500). `all` also includes scratch runs from the `.reeval/runs` directory. Otherwise runs come from the history directory (the `.history` directory by default), and when that directory has no run, scratch runs are returned and `note` is set. Rows have `id`, `outcomes` (`null` when the evaluation is absent), `drift`, `pass`, and `counted`, and `runs` omit `evals`. ## `show` The `show` tool returns one run for a run reference. `format` is `json` (the default) or `md`. `json` is the run record, and `md` is `{ runId, markdown }`. For more information about the run record, see [Run record reference](/reference/run-record). ## `compare` The `compare` tool returns one row per evaluation. `head` and `base` are run references, and `head` defaults to `latest`. When `base` is absent, it is the nearest earlier recorded run with status `complete`, preferring a Git ancestor when one exists. When `base` is set and `head` is absent, `head` is `latest`. Statuses are `regressed`, `fixed`, `drift`, `added`, `removed`, `infra`, and `same`. `changes` lists stack fields that differ. Unless `all` is true, `same` rows are left out and `same` counts them. With no baseline, `base` is `null` and `head` is `{ runId }`. ## `analysis` The `analysis` tool returns `{ runId, entries }` for a run reference, from saved and cached files, newest first, with `saved` before `cached` at the same time. Each entry has `file`, `source` (`saved` or `cached`), and `doc`. `entries` is empty when the run has none. ## `transcript` The `transcript` tool returns one page of lines for a run reference. `attempt` is the key, or `#` when one evaluation has that id. `offset` defaults to 0, and `limit` defaults to 200 (1 to 1000). The result includes `uri`, `total`, and `lines`. An unknown attempt, an id that more than one evaluation has, or a missing file is an error. ## `query` The `query` tool runs one `SELECT` or `WITH` on the `.reeval/history.db` file. Any other keyword, or more than one statement, is an error. A recorded run replaces a scratch copy of the same id. `limit` defaults to 100 (1 to 1000). The result is `{ columns, rows, truncated }`, and `truncated` is true when more rows exist. ## `query_schema` The `query_schema` tool returns `{ objects }` with `name`, `type` (`table` or `view`), and `columns`. It omits `meta`, `files`, `sqlite_*`, `family_lift_m`, `effort_m`, `contrasts_m`, `factor_effects_m`, `flaky_m`, `drift_m`, and `check_streaks_m`. For more information about views and tables, see [Query views and tables reference](/reference/query-views). ## `query_` Each `query_` tool returns the same `{ columns, rows, truncated }` shape. `where` is column equalities. `null` matches `NULL`, a boolean compares as 0 or 1, and an unknown key is rejected. `limit` defaults to 100 (1 to 1000). Each view has its own tool: - `query_lift` - `query_family_lift` - `query_effort` - `query_contrasts` - `query_question_pairs` - `query_attempt_answers` - `query_factor_effects` - `query_skill_reads` - `query_context_use` - `query_skill_files` - `query_flaky_cells` - `query_drift` - `query_failing_attempts` - `query_eval_trend` - `query_verdict_flips` - `query_check_discrimination` - `query_check_rates` - `query_check_streaks` ## `reeval://runs/{runId}` The `run` resource is `reeval://runs/{runId}` for the full run id. The list is newest first, and each title ends in `recorded` or `scratch`. The body is `application/json`. ## `reeval://runs/{runId}/transcripts/{attempt}` The `transcript` resource is `reeval://runs/{runId}/transcripts/{attempt}`. The attempt key is percent-encoded, and the body is `application/jsonl`. The `transcript` tool returns this URI as `uri`.