ProofFlow — Claude Code MCP server: an audit ledger for AI agents
Keeps a local ledger of what an AI agent did: contract, code snapshots, evidence and a check of done criteria. Useful when you need to prove the work matches the claim.
claude mcp add --env PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> --env PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> --transport stdio proofflow -- uvx proofflow-mcpWhat ProofFlow does
ProofFlow records the chain that runs from a work contract to a proof packet. An agent first writes down the objective, the repo path, what it may and may not touch, the tests it must run and the criteria for done. Then come the algorithm decision, a declared cost budget, a snapshot of the code state, evidence, and claims bound to that evidence. The finish is a deterministic evaluation and a markdown export.
Eight steps make up the flow: contract, algorithm decision, cost budget, snapshot, evidence, claim, evaluation, proof packet. The rule is blunt — no case means no workflow, and a claim without evidence is not trusted. Risk hints flag routes that look wrong or too costly, though the server does not act as an automatic judge of your algorithm.
You need uvx and a PROOFFLOW_API_KEY; the base URL goes in PROOFFLOW_BASE_URL. Without the key the server will not start, so set it in your environment first. A Docker route also exists, run from the root of the cloned repository.
What it helps with
- record which files an agent actually changed
- tie an agent's claim to test output
- declare a token and runtime budget before costly work
- check done criteria before a quiet success
- export a proof packet for a reviewer
Example prompts for the agent
- Open a ProofFlow ledger case for this task and record the contract
- Bind the agent's claim to the test output in ProofFlow
- Export a ProofFlow proof packet from the latest snapshot
How to install ProofFlow
Platform CLI
claude mcp add --env PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> --env PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> --transport stdio proofflow -- uvx proofflow-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>
Platform CLI
codex mcp add proofflow --env PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> --env PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> -- uvx proofflow-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>
Config file
{
"mcpServers": {
"proofflow": {
"command": "uvx",
"args": [
"proofflow-mcp"
],
"env": {
"PROOFFLOW_BASE_URL": "<PROOFFLOW_BASE_URL>",
"PROOFFLOW_API_KEY": "<PROOFFLOW_API_KEY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>
Config file
{
"servers": {
"proofflow": {
"type": "stdio",
"command": "uvx",
"args": [
"proofflow-mcp"
],
"env": {
"PROOFFLOW_BASE_URL": "<PROOFFLOW_BASE_URL>",
"PROOFFLOW_API_KEY": "<PROOFFLOW_API_KEY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>
Platform CLI
gemini mcp add -e PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> -e PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> proofflow uvx proofflow-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ProofFlow
How do I install ProofFlow in Claude Code?
Run claude mcp add proofflow -e PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> -- uvx proofflow-mcp, replacing the placeholder with your key.
What does ProofFlow do?
It keeps a ledger of AI agent work: contract, algorithm decision, cost budget, code snapshots, evidence, evaluation and a markdown proof packet.
What does ProofFlow need to run?
It needs uvx and a PROOFFLOW_API_KEY, with the base URL set through PROOFFLOW_BASE_URL. Without the key the server will not start.
