The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Proof listing page.
Proof is an audit trail for AI-written code: it records what the agent changed, what a person actually reviewed, and who signed off. This package is its MCP server.
A Model Context Protocol (MCP) server that exposes a Proof workspace to any MCP-capable client (Claude Desktop, Claude Code, Cursor, Windsurf, custom agents). The server logs into the user's Proof account, talks to the same Supabase project the webapp talks to, and respects the same RLS. Webapp and MCP are two front-ends to one cloud workspace.
Current version: 1.2.0.
Setting this up as an AI agent on someone's behalf? Read
llms-install.mdinstead — same steps, written for you, and it flags the one step that needs a human.
The npm package is @toremlabs/proof-mcp and the command it installs is
proof-mcp, so subcommands run directly:
The CLI prints a device code and a one-click URL of the form
https://proof.toremlabs.com/device?code=XXXX-XXXX. Open it in your browser,
sign in if you aren't already, and confirm the device. The CLI polls in the
background and writes credentials to ~/.proof/credentials.json (chmod 600 on
POSIX) the moment you confirm. Subsequent runs of the MCP are silent.
The login flow rides three Supabase Edge Functions: mcp-device-init,
mcp-device-grant, and mcp-device-poll.
To unlink a machine: npx -y @toremlabs/proof-mcp logout, or open
Settings ▸ Connected devices in the webapp to revoke remotely.
npx -y @toremlabs/proof-mcp whoami confirms which account a machine is
currently linked to.
Claude Desktop. Edit
~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
or %APPDATA%/Claude/claude_desktop_config.json on Windows:
Claude Code / Cursor / Windsurf. Drop a .mcp.json in the workspace root:
Restart the client. The Proof tools appear in the tool menu.
Device pairing writes a refresh token to disk. That works great on a personal machine, but it does not survive disposable/ephemeral environments (CI runners, cloud agent containers, "Claude Code on the web"): the filesystem is wiped between runs, and a Supabase refresh token is single-use under rotation — so a token baked into config dies after the first session.
For those environments, skip pairing and let the server sign in fresh on every boot from your account email + password (a password is not consumed on use, so it works forever with no re-pairing). Set three env vars:
When PROOF_EMAIL + PROOF_PASSWORD are present they take precedence over any
credentials.json, and the MCP server authenticates per boot — no device link
required. Requirements:
PROOF_PASSWORD as a secret. Prefer a dedicated account if your
environment can only expose env vars that are visible to its users.Legacy env names. The server previously shipped as Heuresis, so every variable also accepts its old
HEURESIS_*spelling (HEURESIS_EMAIL,HEURESIS_SNAPSHOT, …). ThePROOF_*name wins when both are set. Machines paired under the old~/.heuresis/directory keep working — reads fall back to it and the next write migrates to~/.proof/.
When the MCP boots in cloud mode it subscribes to the workspace over Supabase
Realtime and notifies the client whenever a nodes, edges, projects, or
ideas row changes. Edits made in the webapp show up in the agent's view
without a manual refresh, and writes from one MCP-connected client reach any
other connected client the same way. Pass --no-realtime to disable the
subscription (useful if the chatter is noisy or the client logs every
notification). The preference is saved to ~/.proof/config.json so the flag
only needs to be passed once.
53 tools total: 49 data tools against the cloud workspace, plus 4 operator tools that drive the same ideation operators the webapp uses.
Reads. get_workspace_summary, list_projects, get_project_graph,
get_subtree, list_concepts, list_edges, get_concept, search_concepts,
find_concepts, find_orphans, list_recent_decisions. Most agent sessions
start with get_workspace_summary or list_projects.
Concept writes. add_concept, update_concept, bulk_add_concepts,
set_parent, link_concepts, add_kref, validate_concept, set_standing,
archive_concept, unarchive_concept, star_concept, remove_concept,
remove_concepts.
Idea & project writes. create_idea, rename_idea, recolor_idea,
set_idea_members, add_to_idea, delete_idea, create_project,
update_project, delete_project.
Agent runs & handoffs. list_agent_runs, get_agent_run,
update_agent_run, list_pending_handoffs, claim_handoff.
Evidence, proof & review. add_evidence, add_challenge, record_proof,
get_concept_proof, list_proofs, list_verification_records,
get_verification_record, submit_review_summary.
Every write that targets a concept stamps a row in public.provenance
with origin='mcp', so the webapp's session log shows which surface and which
device made the change. Writes at the idea, project or agent-run level do not:
a provenance row is keyed to a node (node_id NOT NULL), and those operations
have no single concept to point at.
Operators (4). run_operator (generate candidates with Branch / Matrix /
ASIT / TRIZ / Combine / Free / Contradiction), run_operator_and_commit (same,
plus commit the result in one round-trip), expand_concept (recursive Branch;
expansion is geometric, so it is capped by the number of model calls it makes,
not by depth × breadth), and get_run (fetch a prior operator run).
Tool input shapes mirror their counterparts in the webapp's src/agent/tools.ts,
so an agent that uses both surfaces sees a uniform contract.
Without credentials, the server can read a JSON workspace export from disk and
expose the read-only tool set (get_workspace_summary, list_projects,
search_concepts, get_concept, get_subtree, get_project_graph,
list_recent_decisions). Point PROOF_SNAPSHOT at the file:
Export a workspace from the webapp via Settings → Workspace → Export. This mode is a convenience for offline / read-only use; cloud mode is the primary path.
AGPL-3.0-or-later.