# Iris MCP server

> Scores agent outputs for quality, safety, and cost using deterministic rules and an optional LLM judge.

- Repository: https://github.com/iris-eval/mcp-server
- Page: https://hostedmcp.org/servers/iris-eval/mcp-server
- Transport: stdio
- Stars: 10
- License: MIT
- Latest version: 0.21.0

## Install

### Claude Code

```sh
claude mcp add --env 'IRIS_ANTHROPIC_API_KEY=<YOUR_IRIS_ANTHROPIC_API_KEY>' --env 'IRIS_API_KEY=<YOUR_IRIS_API_KEY>' --env 'IRIS_OPENAI_API_KEY=<YOUR_IRIS_OPENAI_API_KEY>' --env 'IRIS_WEBHOOK_SECRET=<YOUR_IRIS_WEBHOOK_SECRET>' mcp-server -- npx -y @iris-eval/mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_ANTHROPIC_API_KEY": "<YOUR_IRIS_ANTHROPIC_API_KEY>",
        "IRIS_API_KEY": "<YOUR_IRIS_API_KEY>",
        "IRIS_OPENAI_API_KEY": "<YOUR_IRIS_OPENAI_API_KEY>",
        "IRIS_WEBHOOK_SECRET": "<YOUR_IRIS_WEBHOOK_SECRET>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_ANTHROPIC_API_KEY": "<YOUR_IRIS_ANTHROPIC_API_KEY>",
        "IRIS_API_KEY": "<YOUR_IRIS_API_KEY>",
        "IRIS_OPENAI_API_KEY": "<YOUR_IRIS_OPENAI_API_KEY>",
        "IRIS_WEBHOOK_SECRET": "<YOUR_IRIS_WEBHOOK_SECRET>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@iris-eval/mcp-server"],"env":{"IRIS_ANTHROPIC_API_KEY":"<YOUR_IRIS_ANTHROPIC_API_KEY>","IRIS_API_KEY":"<YOUR_IRIS_API_KEY>","IRIS_OPENAI_API_KEY":"<YOUR_IRIS_OPENAI_API_KEY>","IRIS_WEBHOOK_SECRET":"<YOUR_IRIS_WEBHOOK_SECRET>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_ANTHROPIC_API_KEY": "<YOUR_IRIS_ANTHROPIC_API_KEY>",
        "IRIS_API_KEY": "<YOUR_IRIS_API_KEY>",
        "IRIS_OPENAI_API_KEY": "<YOUR_IRIS_OPENAI_API_KEY>",
        "IRIS_WEBHOOK_SECRET": "<YOUR_IRIS_WEBHOOK_SECRET>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-server --env 'IRIS_ANTHROPIC_API_KEY=<YOUR_IRIS_ANTHROPIC_API_KEY>' --env 'IRIS_API_KEY=<YOUR_IRIS_API_KEY>' --env 'IRIS_OPENAI_API_KEY=<YOUR_IRIS_OPENAI_API_KEY>' --env 'IRIS_WEBHOOK_SECRET=<YOUR_IRIS_WEBHOOK_SECRET>' -- npx -y @iris-eval/mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-server]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]

[mcp_servers.mcp-server.env]
IRIS_ANTHROPIC_API_KEY = "<YOUR_IRIS_ANTHROPIC_API_KEY>"
IRIS_API_KEY = "<YOUR_IRIS_API_KEY>"
IRIS_OPENAI_API_KEY = "<YOUR_IRIS_OPENAI_API_KEY>"
IRIS_WEBHOOK_SECRET = "<YOUR_IRIS_WEBHOOK_SECRET>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'IRIS_ANTHROPIC_API_KEY=<YOUR_IRIS_ANTHROPIC_API_KEY>' -e 'IRIS_API_KEY=<YOUR_IRIS_API_KEY>' -e 'IRIS_OPENAI_API_KEY=<YOUR_IRIS_OPENAI_API_KEY>' -e 'IRIS_WEBHOOK_SECRET=<YOUR_IRIS_WEBHOOK_SECRET>' mcp-server npx -- -y @iris-eval/mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_ANTHROPIC_API_KEY": "<YOUR_IRIS_ANTHROPIC_API_KEY>",
        "IRIS_API_KEY": "<YOUR_IRIS_API_KEY>",
        "IRIS_OPENAI_API_KEY": "<YOUR_IRIS_OPENAI_API_KEY>",
        "IRIS_WEBHOOK_SECRET": "<YOUR_IRIS_WEBHOOK_SECRET>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `IRIS_ANTHROPIC_API_KEY` | no | yes | Enables evaluate_with_llm_judge and verify_citations with an Anthropic model. Optional: the deterministic rules never need a key |
| `IRIS_API_KEY` | no | yes | API key for HTTP authentication. Required to bind the HTTP transport or the dashboard beyond loopback (0.0.0.0, a LAN address, a container): without it the server refuses to start |
| `IRIS_OPENAI_API_KEY` | no | yes | Enables evaluate_with_llm_judge and verify_citations with an OpenAI model. Optional: the deterministic rules never need a key |
| `IRIS_WEBHOOK_SECRET` | no | yes | The signing key of that webhook (any string, or whsec_ + base64); the iris format refuses to run without one |
| `IRIS_ALLOWED_ORIGINS` | no | no | Comma-separated Origin allowlist for the HTTP transport and dashboard CORS (default http://localhost:*) |
| `IRIS_ALLOW_UNAUTHENTICATED` | no | no | Set to 1 to run a non-loopback bind with NO API key on purpose (lifts the startup refusal; the network is then your boundary) |
| `IRIS_API_KEY_FILE` | no | no | Path to a file whose trimmed contents are the API key (the secret-file pattern Docker and Kubernetes mount). Set this or IRIS_API_KEY, not both; further keys and rotation are security.apiKeys in config.json |
| `IRIS_CITATION_ALLOW_FETCH` | no | no | Let verify_citations fetch URLs (off by default); a tool argument can turn it off for a call, never on |
| `IRIS_CITATION_DOMAINS` | no | no | Comma-separated domain allowlist for verify_citations fetches (only consulted when IRIS_CITATION_ALLOW_FETCH is on); a tool argument can narrow it, never add to it |
| `IRIS_CITATION_MAX_COST_USD_TOTAL` | no | no | The most one verify_citations call may spend on judge calls, in USD (default 1); max_cost_usd_total can lower it, never raise it |
| `IRIS_DASHBOARD` | no | no | Start the dashboard alongside the server (same as --dashboard) |
| `IRIS_DASHBOARD_HOST` | no | no | Bind host for the dashboard (default 127.0.0.1); same as --dashboard-host |
| `IRIS_DASHBOARD_PORT` | no | no | Dashboard port (default 6920); IRIS_PORT is the MCP HTTP transport port (default 3000) |
| `IRIS_DB_PATH` | no | no | SQLite database path |
| `IRIS_HOME` | no | no | Directory for the database, custom rules and preferences (default ~/.iris) |
| `IRIS_HOST` | no | no | Bind host for the HTTP transport (default 127.0.0.1); only used with --transport http |
| `IRIS_LLM_JUDGE_DAILY_BUDGET_USD` | no | no | What every judge call together may spend per UTC day, per tenant, in USD (default 1): the relevance judge, evaluate_with_llm_judge and verify_citations. Past it no judge call is made |
| `IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL` | no | no | Hard cap on the worst-case cost of one LLM judge call (default 0.25); max_cost_usd can lower it for a call, never raise it |
| `IRIS_LOG_LEVEL` | no | no | Log level: debug, info, warn, error |
| `IRIS_MAX_INPUT_ELEMENTS` | no | no | The most array elements and object keys one input may hold before it is validated (default 100000): a tool call's arguments, and a dashboard or OTLP JSON request body. A tool call over it gets an error result; a body, 413. OTLP protobuf has its own ceiling, one element per 5 bytes of the request size limit |
| `IRIS_MAX_TOOL_INPUT_ELEMENTS` | no | no | The name of IRIS_MAX_INPUT_ELEMENTS before 0.21.0, read when the new name is unset |
| `IRIS_OTEL_ENDPOINT` | no | no | OTLP/HTTP collector URL; when set, every stored trace is also exported as OpenTelemetry spans (best-effort, asynchronous) |
| `IRIS_OTEL_HEADERS` | no | no | Comma-separated key=value headers sent with every OTLP export (for example an auth token for your collector) |
| `IRIS_OTEL_SERVICE_NAME` | no | no | service.name resource attribute on exported spans (default iris-eval) |
| `IRIS_OTEL_TIMEOUT_MS` | no | no | Timeout in milliseconds for each OTLP export request |
| `IRIS_PORT` | no | no | MCP HTTP transport port (default 3000); only used with --transport http |
| `IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD` | no | no | The name of IRIS_LLM_JUDGE_DAILY_BUDGET_USD before 0.21.0. Read when the new name is unset, and it then limits every judge call |
| `IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST` | no | no | Relevance judge calls one request may make (default 20) |
| `IRIS_RELEVANCE_JUDGE_MODEL` | no | no | A priced judge model; answers_the_ask then asks it on every evaluation with input, sending that input and output to the model's provider, and gates on its verdict (off by default) |
| `IRIS_RELEVANCE_JUDGE_REDACT` | no | no | on (default) replaces the PII and credentials no_pii flags before the relevance judge sends input and output to its provider; off sends them as they are |
| `IRIS_SEARCH_BUDGET_MS` | no | no | How long one trace search may read before it answers with the matches found so far, in milliseconds (50-60000, default 1000) |
| `IRIS_SEARCH_INDEX` | no | no | on (default) or off. off keeps no full-text index of the traces: writes are cheaper, and a search reads the traces within its time budget |
| `IRIS_SQLITE_DRIVER` | no | no | Which SQLite driver holds the database: native (better-sqlite3, the default) or node (Node's built-in node:sqlite, Node 22.13+). Unset: native, falling back to node when the native module cannot load |
| `IRIS_TRANSPORT` | no | no | Transport: stdio (default) or http; same as --transport |
| `IRIS_WEBHOOK_URL` | no | no | The receiver of the webhook that fires on a moment (docs/webhooks.md); merged over notify.webhook in config.json |

## Tools (17)

- `log_trace`
- `evaluate_output`
- `get_traces`
- `list_rules`
- `deploy_rule`
- `delete_rule`
- `delete_trace`
- `evaluate_with_llm_judge`
- `verify_citations`
- `compare_runs`
- `compare_traces`
- `evaluate_runs`
- `score`
- `name`
- `type`
- `config`
- `weight`

## FAQ

### Does Iris require an account or an LLM to work?

No, you can run Iris on your machine with no account and no SDK. It uses 28 built-in deterministic rules that require no LLM calls.

### Where is my data stored?

Your agent's runs are stored in a SQLite database locally on your disk.

### How can I capture agent traces without the model choosing to call a tool?

You can use the HTTP ingest endpoint to send traces via plain HTTP, or use the specific Claude Code capture plugin.

### Is my data sent to the cloud?

By default, nothing leaves your machine unless you explicitly enable an OpenTelemetry endpoint, an LLM judge, or a webhook.
