---
title: MCP server
description: Mount @izri/mcp in Claude Code, Cursor, or Windsurf so your coding agent can score its own pull requests.
order: 30
---

# MCP server

`@izri/mcp` exposes Izri's signals as Model Context Protocol tools. The point is closing the loop: the agent that wrote the diff can ask whether the diff is safe to merge, and act on the answer, without a human relaying the verdict.

## Setup

The server needs the same two environment variables as the CLI: `IZRI_API_URL` and `IZRI_API_TOKEN`.

### Claude Code

```bash
claude mcp add izri \
  --env IZRI_API_URL=https://api.izri.ai \
  --env IZRI_API_TOKEN=izri_xxxxxxxxxxxx \
  -- npx -y @izri/mcp
```

### Cursor / Windsurf

Add to your MCP configuration file:

```json
{
  "mcpServers": {
    "izri": {
      "command": "npx",
      "args": ["-y", "@izri/mcp"],
      "env": {
        "IZRI_API_URL": "https://api.izri.ai",
        "IZRI_API_TOKEN": "izri_xxxxxxxxxxxx"
      }
    }
  }
}
```

## The nine tools

### Discovery

**`list_projects`** — lists the projects your token can reach. Read-only and safe to call any time.

Call this first. An API token only sees projects in its own organization, and skipping discovery is how agents land on a confusing cross-organization `NOT_FOUND`.

**`get_scope_config`** — reads the project's scope config: the team vocabulary the analyzer reasons against (modules, categories, sensitive paths), plus its version and source (`derived`, `user`, or `merged`). Free on every tier. Returns null when nothing has been derived yet.

### The headline verdict

**`score_pr`** — the answer to *"is this delta safe to merge?"* in one read. Returns the `izri/quality` umbrella verdict (`passing` / `failing` / `unknown`), per-signal child contexts, aggregate scores, hard findings, and LLM insights.

This is the tool an agent should reach for by default. The rest are drill-downs.

### Running tests

**`run_suite`** — triggers a test run and returns a `test_run_id` immediately. The run is asynchronous; poll `get_results`.

**`get_results`** — fetches a run's current state by ID: status (`PENDING` / `RUNNING` / `PASSED` / `FAILED` / `ERROR`), counts, duration, and logs once complete. Pass `enriched=true` for cached LLM insights — Hobby tier or higher.

### Signal drill-downs

**`check_pr_scope`** — compares a PR's declared scope (title, labels, body) against the actual diff and flags drift. Returns the deterministic rule layer by default; `semantic: true` adds the LLM intent comparison and costs AI tokens.

**`check_hallucinations`** — the per-file diff-coverage breakdown for a delta: `coverage_score` 0–100, file buckets (covered / partial / uncovered / not-instrumented), rule findings, and per-file covered and uncovered lines.

**`check_test_efficacy`** — the same shape as `check_hallucinations`, but addressed by `test_run_id` instead of by delta. Use it right after `run_suite` when you want the verdict for *that exact attempt* rather than the latest one on the delta.

**`get_suggestions`** — aggregates recurring themes, likely causes, and suspected flakes across the project's recent reports. Answers "what's the pattern in our recent PRs?" Hobby tier or higher; free-tier callers get `PAYMENT_REQUIRED`.

## A working loop

The pattern worth teaching an agent:

1. `list_projects` once, to get a valid project ID.
2. Write the change, open the PR.
3. `score_pr` — read the umbrella verdict.
4. If failing, drill in: `check_pr_scope` for scope drift, `check_hallucinations` for untested changes.
5. Fix, push, `score_pr` again.

Note step 5. Izri never proposes the patch; it reports what is wrong and the agent decides what to do about it.

## Tier gating

`list_projects`, `get_scope_config`, `score_pr`, `run_suite`, `get_results`, `check_pr_scope`, `check_hallucinations`, and `check_test_efficacy` work on every plan. `get_suggestions` and enriched results need Hobby or higher. See [plans and quotas](/docs/reference/plans-and-quotas).

## Related

- [CLI](/docs/install/cli) — the same signals from a terminal.
- [The four signals](/docs/signals/overview) — what each tool is actually measuring.