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.
Govern your AI coding agent: frame the work, review the changes, keep a signed decision record.
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
Current version: 1.2.0.
Setting this up as an AI agent on someone's behalf? Read
llms-install.md instead — same steps, written for you,
and it flags the one step that needs a human.
Install
npm install -g @toremlabs/proof-mcp
# or on demand without installing:
npx -y @toremlabs/proof-mcp
The npm package is @toremlabs/proof-mcp and the command it installs is
proof-mcp, so subcommands run directly:
npx -y @toremlabs/proof-mcp login
Quickstart
1. Link this machine to your Proof account
npx -y @toremlabs/proof-mcp login
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.
2. Point your MCP client at it
Claude Desktop. Edit
~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
or %APPDATA%/Claude/claude_desktop_config.json on Windows:
Restart the client. The Proof tools appear in the tool menu.
3. CLI subcommands
npx -y @toremlabs/proof-mcp whoami # show the linked account + device
npx -y @toremlabs/proof-mcp logout # delete the credentials file
npx -y @toremlabs/proof-mcp --help # all options
npx -y @toremlabs/proof-mcp --no-realtime # boot the server with live sync off (persisted)
npx -y @toremlabs/proof-mcp --realtime # re-enable live sync
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:
[email protected] # your Proof account email
PROOF_PASSWORD=your-account-password # secret — store it in a secrets manager
PROOF_ANON_KEY=sb_publishable_... # project anon/publishable key (public, not a secret)
# optional: PROOF_SUPABASE_URL=... # defaults to the production Proof project
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:
Email + password sign-in must be enabled for the Supabase project, and the
account must have a password set (passwordless / magic-link-only accounts
need a password added first).
Treat 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, …). The PROOF_* 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/.
Live sync
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.
Tools
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.
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.
Snapshot mode (read-only)
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.
