The Vivarium MCP server (@aletheia-works/vivarium-mcp) speaks Model Context Protocol over stdio and exposes a set of tools (catalogue enumeration, recipe lookup, verdict snapshots, error-to-recipe matching, plus scaffolders for new recipes and for branch-fix / fix-candidate verification). 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 full list and per-tool inputs are in the section below.

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.

• prepare_new_recipe(project, issue, title, base_image?, repo_owner?, layer?) — scaffolding helper for authoring a brand-new recipe in one step. Returns the validated slug, the exact mise run recipes:new / mise run recipes:verify commands, a placeholder recipe.json to drop into the recipe directory (validates against docs/site/public/spec/recipe.schema.json), an optional docs/site/_data/projects.json row (only when the recipe debuts a new upstream project), the commit-subject template, and a sequenced next-steps checklist. Layer 2 has the canonical scaffolder; Layer 1 / 3 fall back to copying from an existing recipe.

• prepare_fix_candidate(slug, fork_url, branch, upstream_pr?, package?, purpose?) — scaffolding helper for registering a fix-candidate spec on an existing Layer 1 recipe so the page runs the fork branch's wheel side-by-side with the released build (per ADR-0040). Returns the fix-candidate.json content the agent should write, the recommended commit subject + PR title, a ready-to-paste PR body, and the exact gh / git commands to fork-and-clone aletheia-works/vivarium, branch off main, drop the spec in, commit, push, and open the cross-repo PR. Layer 1 only (Layers 2 / 3 use verify_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."