Iris — Claude Code MCP server: what it does, how to install
Evaluates agent runs locally for safety, quality, and cost without accounts or remote SDKs.
claude mcp add --env IRIS_API_KEY=<IRIS_API_KEY> --env IRIS_API_KEY_FILE=<IRIS_API_KEY_FILE> --env IRIS_ALLOW_UNAUTHENTICATED=<IRIS_ALLOW_UNAUTHENTICATED> --env IRIS_DB_PATH=<IRIS_DB_PATH> --env IRIS_SQLITE_DRIVER=<IRIS_SQLITE_DRIVER> --transport stdio iris -- npx -y @iris-eval/mcp-serverWhat Iris does
Iris stores agent execution traces in a local SQLite file. The engine applies 26 deterministic rules to each run without calling external model APIs. It inspects tool calls, checks for prompt injection patterns, catches personal data leaks, and tracks token costs.
A model judge can be enabled for semantic checks, protected by a per-run cost cap. Inspection results and failed runs display in a local web interface at http://localhost:6920.
The server requires Node.js 22.13 or newer. It fails on older runtimes. Records stay on your machine unless you configure OpenTelemetry trace exports or webhook alerts.
What it helps with
- catch prompt injections and hidden directives in agent input
- detect accidental leaks of sensitive personal data
- track hallucination markers and invalid tool calls
- enforce strict financial spending caps across agent executions
Example prompts for the agent
- Evaluate the latest agent run against the safety and PII rules
- Audit the tool call sequence and check for hallucination markers
- Inspect the cost thresholds and rule failures logged in Iris
How to install Iris
Platform CLI
claude mcp add --env IRIS_API_KEY=<IRIS_API_KEY> --env IRIS_API_KEY_FILE=<IRIS_API_KEY_FILE> --env IRIS_ALLOW_UNAUTHENTICATED=<IRIS_ALLOW_UNAUTHENTICATED> --env IRIS_DB_PATH=<IRIS_DB_PATH> --env IRIS_SQLITE_DRIVER=<IRIS_SQLITE_DRIVER> --transport stdio iris -- npx -y @iris-eval/mcp-serverReplace <…> with your own values. 26 more environment variables are in the server README
Platform CLI
codex mcp add iris --env IRIS_API_KEY=<IRIS_API_KEY> --env IRIS_API_KEY_FILE=<IRIS_API_KEY_FILE> --env IRIS_ALLOW_UNAUTHENTICATED=<IRIS_ALLOW_UNAUTHENTICATED> --env IRIS_DB_PATH=<IRIS_DB_PATH> --env IRIS_SQLITE_DRIVER=<IRIS_SQLITE_DRIVER> -- npx -y @iris-eval/mcp-serverReplace <…> with your own values. 26 more environment variables are in the server README
Config file
{
"mcpServers": {
"iris": {
"command": "npx",
"args": [
"-y",
"@iris-eval/mcp-server"
],
"env": {
"IRIS_API_KEY": "<IRIS_API_KEY>",
"IRIS_API_KEY_FILE": "<IRIS_API_KEY_FILE>",
"IRIS_ALLOW_UNAUTHENTICATED": "<IRIS_ALLOW_UNAUTHENTICATED>",
"IRIS_DB_PATH": "<IRIS_DB_PATH>",
"IRIS_SQLITE_DRIVER": "<IRIS_SQLITE_DRIVER>"
}
}
}
}Replace <…> with your own values. 26 more environment variables are in the server README
Config file
{
"servers": {
"iris": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@iris-eval/mcp-server"
],
"env": {
"IRIS_API_KEY": "<IRIS_API_KEY>",
"IRIS_API_KEY_FILE": "<IRIS_API_KEY_FILE>",
"IRIS_ALLOW_UNAUTHENTICATED": "<IRIS_ALLOW_UNAUTHENTICATED>",
"IRIS_DB_PATH": "<IRIS_DB_PATH>",
"IRIS_SQLITE_DRIVER": "<IRIS_SQLITE_DRIVER>"
}
}
}
}Replace <…> with your own values. 26 more environment variables are in the server README
Platform CLI
gemini mcp add -e IRIS_API_KEY=<IRIS_API_KEY> -e IRIS_API_KEY_FILE=<IRIS_API_KEY_FILE> -e IRIS_ALLOW_UNAUTHENTICATED=<IRIS_ALLOW_UNAUTHENTICATED> -e IRIS_DB_PATH=<IRIS_DB_PATH> -e IRIS_SQLITE_DRIVER=<IRIS_SQLITE_DRIVER> iris npx -y @iris-eval/mcp-serverReplace <…> with your own values. 26 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Iris
How to install Iris in Claude Code?
Run `claude mcp add mcp-server -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`.
What does Iris do?
It records agent execution traces into a local SQLite database and evaluates them across 26 deterministic checks for cost, safety, and quality.
What prerequisites does Iris require?
You need Node.js version 22.13 or later. Verify your local runtime version with node --version.
