The Vivarium MCP server (@aletheia-works/vivarium-mcp) speaks Model Context Protocol over stdio and exposes five tools: list_recipes, get_recipe, lookup_verdict, match_error, and verify_branch_fix. An agent can browse the catalogue, fetch metadata for a given recipe, pull deployed Layer 2 / 3 verdict snapshots, and scaffold the AI-slop verification loop end-to-end.

The first JSR / npm publish is intentionally on hold. Vivarium overall and the MCP server's feature surface are both judged not yet finished — pushing v1 now would crystallise an interface still under iteration. The maintainer will announce timing separately. Until then, the working install path is local clone.

git clone https://github.com/aletheia-works/vivarium.git
cd vivarium/packages/mcp-server
bun install
bun run build
# → produces dist/index.js (the entry point your client will spawn)

Note the absolute path to dist/index.js. The MCP client config will spawn it via node.

Every MCP client takes essentially the same JSON snippet — a command and an args array:

{
"mcpServers": {
  "vivarium": {
    "command": "node",
    "args": ["/abs/path/to/vivarium/packages/mcp-server/dist/index.js"]
  }
}
}

What differs is where you put it:

The authoritative client list is at modelcontextprotocol.io/clients. Per-client config paths drift over time; consult upstream when anything looks off.

• list_recipes(layer?, project?, q?) — filtered enumeration of the catalogue. layer is the integer 1/2/3, project matches the upstream project (e.g. "pandas"), q is a substring search across slug, project, and title.

• get_recipe(slug) — full metadata for one recipe (title, project, issue, page URL, verdict snapshot URL, GitHub source URL). Returns { found: false, error } on unknown slug.

• lookup_verdict(slug) — Layer 1 returns { kind: "live", page_url, note } (the verdict is computed in-browser at view time). Layer 2 / 3 returns { kind: "snapshot", snapshot: { verdict, exit_code, image_digest, stdout, stderr_tail, ... } }.

• match_error(text, limit?) — score the catalogue against a pasted error message or stack trace by mechanical token overlap. No LLM, no fuzzy matching — exact token hits against symptom / tags / project / slug, weighted per source.

• verify_branch_fix(slug, fix_url? | fix_source?) — scaffolding helper for the AI-slop verification loop (NOT an execution engine). Layer 1 returns Path A: a recipe-page compare_url with the fix pre-loaded via ?fix_url= or ?fix=<base64url>. Layer 2 / 3 returns Path B: a /repro/compare deep-link plus the gh workflow run branch-fix-verdict.yml command the contributor runs. Full walkthrough: Verify a branch-fix.

The match_error scoring is bit-identical to the error → recipe matcher page. MCP and UI return the same ranked candidates.

• No dist/index.js. Means bun run build wasn't run. Run bun install && bun run build in packages/mcp-server/ once.

• Some clients can't expand the home-directory shortcut or relative paths. Use a fully-qualified absolute path — /Users/<you>/code/vivarium/.../dist/index.js, not $HOME/code/vivarium/....

• Recipes seem stale. The server caches https://aletheia-works.github.io/vivarium/api/recipes.json with a 5-minute TTL and falls back to a build-time snapshot offline. Restart the MCP server to force a refetch.

• "Layer 1 verdict isn't a snapshot." By design — Layer 1's site of truth is the browser at view time (Contract v1). The agent should treat kind: "live" as "open this URL for the human to verify."