Provides an audit trail for AI-written code by recording agent changes, human reviews, and signed decision records.
Also known as ToremLabs/proof-mcp, proof-mcp, @toremlabs/proof-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Sep 4, 2026
- License
- AGPL-3.0
What is Proof MCP?
Proof provides an audit trail for AI-written code by recording agent changes, human reviews, and signed decision records.
Summary generated from the project's README
About Proof MCP server
Proof provides a specialized audit trail for code developed by AI agents. It tracks agent modifications, human reviews, and signed decision records to ensure accountability in the development process. This MCP server connects to a Proof cloud workspace, allowing AI clients like Claude Desktop, Cursor, Windsurf, and Claude Code to interact with the same data used in the web application.
Users can set up the server on local machines using a device-pairing login flow that saves credentials to a local directory. For headless environments like CI runners or cloud containers, the server supports authentication via email and password environment variables. It also offers a read-only snapshot mode that allows an agent to inspect a JSON workspace export from a local file without needing an active account.
The server includes 53 tools, including data tools for managing concepts, ideas, and projects, alongside four operator tools for generating candidates through methods like Branch or Matrix. It features live synchronization via Supabase Realtime, ensuring that changes made in the web app appear immediately in the agent's view.
What you can do with it
- 1Audit AI code changesAn AI agent can record its specific modifications and decision history to create a verifiable provenance log.
- 2Manage workspace conceptsA developer can instruct an agent to organize project structures by adding, linking, or archiving concepts.
- 3Run ideation operatorsAn AI client can trigger complex reasoning patterns like TRIZ or Matrix to generate new development candidates.
Written from the project's README. Every use case is checked against a quote from it.
How to install Proof MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Proof MCP in Claude Code
$ claude mcp add proof-mcp -- npx -y @toremlabs/proof-mcpInstall Proof MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"proof-mcp": {
"command": "npx",
"args": [
"-y",
"@toremlabs/proof-mcp"
]
}
}
}Install Proof MCP in VS Code
.vscode/mcp.json
{
"servers": {
"proof-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@toremlabs/proof-mcp"
]
}
}
}Install Proof MCP in VS Code CLI
$ code --add-mcp '{"name":"proof-mcp","type":"stdio","command":"npx","args":["-y","@toremlabs/proof-mcp"]}'Install Proof MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"proof-mcp": {
"command": "npx",
"args": [
"-y",
"@toremlabs/proof-mcp"
]
}
}
}Install Proof MCP in Codex
$ codex mcp add proof-mcp -- npx -y @toremlabs/proof-mcpInstall Proof MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.proof-mcp] command = "npx" args = ["-y", "@toremlabs/proof-mcp"]
Install Proof MCP in Gemini CLI
$ gemini mcp add -s user proof-mcp npx -- -y @toremlabs/proof-mcpInstall Proof MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"proof-mcp": {
"command": "npx",
"args": [
"-y",
"@toremlabs/proof-mcp"
]
}
}
}Configuration
PROOF_ANON_KEYPROOF_EMAILPROOF_PASSWORDPROOF_SNAPSHOT
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletoremlabs/proof-mcp is public and reachablegithub.com/toremlabs/proof-mcp ↗Pass
- Package names this repository as its source@toremlabs/proof-mcp names toremlabs/proof-mcp as sourcenpmjs.com/package/@toremlabs/proof-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-04github.com/toremlabs/proof-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @toremlabs/proof-mcpPass
- No critical advisory in the package or its dependencies142 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@toremlabs/proof-mcp
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.
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:
{
"mcpServers": {
"proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
}
}
Claude Code / Cursor / Windsurf. Drop a .mcp.json in the workspace root:
{
"mcpServers": {
"proof": { "command": "npx", "args": ["-y", "@toremlabs/proof-mcp"] }
}
}
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
Headless mode (CI, cloud agents, disposable containers)
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:
PROOF_EMAIL=you@example.com # 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_PASSWORDas 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/.
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.
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.
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 PROOF_SNAPSHOT="/absolute/path/to/your-export.json"
npx @toremlabs/proof-mcp
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.
License
AGPL-3.0-or-later.
Proof MCP questions
How do I add Proof MCP to Claude Code?
Run claude mcp add proof-mcp -- npx -y @toremlabs/proof-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Proof MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I link my machine to my Proof account?
Run npx -y @toremlabs/proof-mcp login to receive a device code and a URL to confirm the connection in your browser.
Can I use Proof in headless environments like CI or cloud agents?
Yes, you can skip device pairing by setting PROOF_EMAIL, PROOF_PASSWORD, and PROOF_ANON_KEY environment variables to sign in fresh on every boot.
How can I use Proof in a read-only mode without credentials?
You can use Snapshot mode by pointing the PROOF_SNAPSHOT environment variable to a JSON workspace export file.
Does the server support live synchronization?
Yes, when booted in cloud mode, it uses Supabase Realtime to notify the client of changes to projects, ideas, or concepts.