ProofFlow MCP Server

MCP (Model Context Protocol) server that exposes ProofFlow's audit capabilities as tools for Claude Code and Codex.

What it does

Lets AI coding assistants trigger ProofFlow workflows directly:

• Scan folders — index files with SHA-256 hashes, create audit Cases
• Code review — analyze git diffs, generate evidence-backed risk claims
• Suggest actions — generate file organization suggestions
• Approve & execute — run pending actions (with policy gate awareness)
• Export Proof Packets — generate shareable markdown audit reports
• Search — full-text search across indexed artifacts
• Undo — reverse executed actions

Prerequisites

• Python 3.11+
• ProofFlow backend running on http://127.0.0.1:8787

Installation

cd mcp-server
pip install -e .

For development (includes test dependencies):

pip install -e ".[dev]"

Note: Install in a separate virtualenv from the backend to avoid starlette version conflicts between FastAPI and the MCP SDK.

Configuration

Claude Code

Add to your project's .mcp.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "proofflow": {
      "command": "python",
      "args": ["-m", "proofflow_mcp"],
      "env": {
        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "proofflow": {
      "command": "proofflow-mcp",
      "env": {
        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

Codex

Add to your Codex MCP configuration with the same command/args pattern.

Environment Variables

Available Tools

Usage Example

In Claude Code, once configured:

> Review the code changes in this repo for safety

Claude will call proofflow_review with the current repo path,
creating an AgentGuard Case with evidence-backed claims.

Running Tests

cd mcp-server
python -m pytest tests/ -v

Running the Server Directly

python -m proofflow_mcp

The server communicates via stdio (stdin/stdout) per the MCP protocol.

Architecture

Claude Code / Codex
    ↓ (MCP stdio)
ProofFlow MCP Server
    ↓ (HTTP)
ProofFlow Backend (localhost:8787)
    ↓
SQLite DB + Local Files

The MCP server is a thin adapter — all business logic lives in the ProofFlow backend.