Iris MCP Server

by iris-evalio.github.iris-eval/mcp-serverv0.20.0

Agent evaluation and observability: trace logging, output quality evaluation, cost tracking, built-in eval rules, a real-time dashboard and PII detection.

9Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active1d ago

Install Iris MCP server

claude mcp add iris-eval -e IRIS_API_KEY='<iris-api-key>' -e IRIS_ANTHROPIC_API_KEY='<iris-anthropic-api-key>' -e IRIS_OPENAI_API_KEY='<iris-openai-api-key>' -e IRIS_WEBHOOK_SECRET='<iris-webhook-secret>' -- npx -y @iris-eval/mcp-server

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_API_KEY": "<iris-api-key>",
        "IRIS_ANTHROPIC_API_KEY": "<iris-anthropic-api-key>",
        "IRIS_OPENAI_API_KEY": "<iris-openai-api-key>",
        "IRIS_WEBHOOK_SECRET": "<iris-webhook-secret>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_API_KEY": "<iris-api-key>",
        "IRIS_ANTHROPIC_API_KEY": "<iris-anthropic-api-key>",
        "IRIS_OPENAI_API_KEY": "<iris-openai-api-key>",
        "IRIS_WEBHOOK_SECRET": "<iris-webhook-secret>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "iris-eval": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_API_KEY": "<iris-api-key>",
        "IRIS_ANTHROPIC_API_KEY": "<iris-anthropic-api-key>",
        "IRIS_OPENAI_API_KEY": "<iris-openai-api-key>",
        "IRIS_WEBHOOK_SECRET": "<iris-webhook-secret>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": [
        "-y",
        "@iris-eval/mcp-server"
      ],
      "env": {
        "IRIS_API_KEY": "<iris-api-key>",
        "IRIS_ANTHROPIC_API_KEY": "<iris-anthropic-api-key>",
        "IRIS_OPENAI_API_KEY": "<iris-openai-api-key>",
        "IRIS_WEBHOOK_SECRET": "<iris-webhook-secret>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
IRIS_API_KEY	—	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_API_KEY_FILE	—	—	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_ALLOW_UNAUTHENTICATED	—	—	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_DB_PATH	—	—	SQLite database path
IRIS_SQLITE_DRIVER	—	—	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_SEARCH_BUDGET_MS	—	—	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	—	—	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_LOG_LEVEL	—	—	Log level: debug, info, warn, error
IRIS_HOME	—	—	Directory for the database, custom rules and preferences (default ~/.iris)
IRIS_ANTHROPIC_API_KEY	—	yes	Enables evaluate_with_llm_judge and verify_citations with an Anthropic model. Optional: the deterministic rules never need a key
IRIS_OPENAI_API_KEY	—	yes	Enables evaluate_with_llm_judge and verify_citations with an OpenAI model. Optional: the deterministic rules never need a key
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL	—	—	Hard cap on the worst-case cost of one judge or citation call (default 0.25)
IRIS_RELEVANCE_JUDGE_MODEL	—	—	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_DAILY_BUDGET_USD	—	—	What the relevance judge may spend per UTC day, per tenant, in USD (default 1); past it answers_the_ask reads the ask lexically
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST	—	—	Relevance judge calls one request may make (default 20)
IRIS_RELEVANCE_JUDGE_REDACT	—	—	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_CITATION_ALLOW_FETCH	—	—	Let verify_citations fetch URLs (off by default)
IRIS_DASHBOARD	—	—	Start the dashboard alongside the server (same as --dashboard)
IRIS_DASHBOARD_PORT	—	—	Dashboard port (default 6920); IRIS_PORT is the MCP HTTP transport port (default 3000)
IRIS_PORT	—	—	MCP HTTP transport port (default 3000); only used with --transport http
IRIS_OTEL_ENDPOINT	—	—	OTLP/HTTP collector URL; when set, every stored trace is also exported as OpenTelemetry spans (best-effort, asynchronous)
IRIS_CITATION_DOMAINS	—	—	Comma-separated domain allowlist for verify_citations fetches (only consulted when IRIS_CITATION_ALLOW_FETCH is on)
IRIS_TRANSPORT	—	—	Transport: stdio (default) or http; same as --transport
IRIS_HOST	—	—	Bind host for the HTTP transport (default 127.0.0.1); only used with --transport http
IRIS_ALLOWED_ORIGINS	—	—	Comma-separated Origin allowlist for the HTTP transport and dashboard CORS (default http://localhost:*)
IRIS_DASHBOARD_HOST	—	—	Bind host for the dashboard (default 127.0.0.1); same as --dashboard-host
IRIS_OTEL_HEADERS	—	—	Comma-separated key=value headers sent with every OTLP export (for example an auth token for your collector)
IRIS_OTEL_SERVICE_NAME	—	—	service.name resource attribute on exported spans (default iris-eval)
IRIS_OTEL_TIMEOUT_MS	—	—	Timeout in milliseconds for each OTLP export request
IRIS_WEBHOOK_URL	—	—	The receiver of the webhook that fires on a moment (docs/webhooks.md); merged over notify.webhook in config.json
IRIS_WEBHOOK_SECRET	—	yes	The signing key of that webhook (any string, or whsec_ + base64); the iris format refuses to run without one

Freshness

Active — last maintenance signal 1d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-10-08 · 1d ago · GitHub
Latest release
2026-10-04 · 6d ago · GitHub · v0.20.0
Package published
no data · npm/PyPI
Registry entry updated
2026-10-04 · 6d ago · official registry · v0.20.0

FAQ

›How do I install the Iris MCP server in Claude Code?

Run: claude mcp add iris-eval -e IRIS_API_KEY='<iris-api-key>' -e IRIS_ANTHROPIC_API_KEY='<iris-anthropic-api-key>' -e IRIS_OPENAI_API_KEY='<iris-openai-api-key>' -e IRIS_WEBHOOK_SECRET='<iris-webhook-secret>' -- npx -y @iris-eval/mcp-server. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Iris require an API key?

Yes. It expects IRIS_API_KEY, IRIS_ANTHROPIC_API_KEY, IRIS_OPENAI_API_KEY, IRIS_WEBHOOK_SECRET, of which 4 are secrets.

›Can I use Iris as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Iris in the official MCP registry?

Yes, as io.github.iris-eval/mcp-server.