proofscan

Languages: English | 日本語

MCP Server scanner - eliminate black boxes by capturing JSON-RPC from connection to tools/list.

Overview

proofscan provides complete visibility into MCP (Model Context Protocol) server communication. It operates in three modes:

• CLI – Run single commands to inspect, manage and analyze data
• SHELL – Explore connectors, sessions and RPCs interactively
• PROXY – Capture MCP traffic continuously as a proxy server

Key Capabilities

| Feature | Description | |---------|-------------| | 🔍 Capture | All JSON-RPC messages (requests, responses, notifications) | | 💾 Store | Events in SQLite for efficient querying and analysis | | 🌳 Visualize | Connector → session → RPC hierarchies | | 🔧 Test | MCP tools directly from CLI | | 🎭 Proxy | Multiple MCP servers with unified tool namespace | | 📊 Generate | Public-safe audit trails (POPL) | | 🐚 Interactive | Shell mode with TAB completion | | 📦 Catalog | Search and install MCP servers from registry | | 📈 Analyze | Tool usage analysis across sessions | | 📝 Plans | Validation plans for automated testing | | 🖥️ MCP Apps | Interactive trace viewer UI in Claude Desktop | | 🌍 i18n | Multi-language support (English, 日本語) |

Quick Links

For Users

• 📖 User Guide (日本語) – Complete CLI reference
• 🐚 Shell Mode (日本語) – Interactive shell and @references
• 🎭 Proxy Guide (日本語) – MCP proxy server
• 📦 POPL Guide (日本語) – Public Observable Proof Ledger
• 🔧 MCP Server Setup (日本語) – Setting up MCP servers
• 🖥️ MCP Apps UI (日本語) – Interactive trace viewer UI

For Developers

• CONTRIBUTING.md – Development setup and guidelines

Installation

Global Installation (Recommended)

npm install -g proofscan

Run without Installing

npx proofscan --help

Available Commands

After installation, you can use any of these aliases:

| Command | Description | |---------|-------------| | proofscan | Full command name | | pfscan | Short alias | | pfs | Shortest alias | | psh | Direct shell mode (equivalent to pfscan shell) |

Requirements: Node.js v18+ (v20+ recommended)

Quick Start

1. Initialize Configuration

pfscan config init        # Create configuration
pfscan config path        # Show config location

2. Add an MCP Server

Option A: Import from Claude Desktop config

# Import from file
pfscan connectors import --from mcpServers --file ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or from stdin
cat claude_desktop_config.json | pfscan connectors import --from mcpServers --stdin

Option B: Add manually

pfscan connectors add --id time --stdio "npx -y @modelcontextprotocol/server-time"

Option C: Install from catalog

pfscan catalog install @modelcontextprotocol/server-time --id time

3. Scan and View

pfscan scan start --id time   # Run scan
pfscan                        # View events (default command)
pfscan tree                   # Show structure
pfscan status                 # System status

Core Features

📊 Event Timeline

$ pfscan view --limit 10
Time         Sym Dir St Method              Session      Extra
-------------------------------------------------------------------
21:01:58.743 → → ✓ initialize            f2442c... lat=269ms
21:01:59.018 ← ← ✓ initialize            f2442c...
21:01:59.025 • →   notifications/initi... f2442c...
21:01:59.037 → → ✓ tools/list            f2442c...
21:01:59.049 ← ← ✓ tools/list            f2442c... lat=12ms size=1.0KB

# Real-time monitoring
$ pfscan view -f --connector time

# Export to file
$ pfscan view --export events.csv

🌳 Hierarchical Tree

$ pfscan tree
└── 📦 time
    ├── 📋 f2442c9b... (2 rpcs, 8 events)
    │   ├── ↔️ ✓ tools/list (id=2, 12ms)
    │   └── ↔️ ✓ initialize (id=1, 269ms)
    └── 📋 3cf5a66e... (2 rpcs, 8 events)
        ├── ↔️ ✓ tools/list (id=2, 13ms)
        └── ↔️ ✓ initialize (id=1, 271ms)

🐚 Interactive Shell

$ psh
# Or: pfscan shell

proofscan> pwd
Context: session=f2442c9b (connector=time)

proofscan> tool ls
Found 2 tools: get_current_time, get_timezone

proofscan> ref add mytask @this
✓ Reference 'mytask' saved

proofscan> popl @last --title "Time Server Test"
✓ POPL entry created: 20260104-f2442c9b

🎭 MCP Proxy

# Start proxy with multiple backends
pfscan proxy start --connectors time,weather

# Tools are namespaced: time__get_current_time, weather__get_forecast

Use with Claude Desktop:

{
  "mcpServers": {
    "proofscan-proxy": {
      "command": "pfscan",
      "args": ["proxy", "start", "--all"]
    }
  }
}

🔧 Direct Tool Testing

pfscan tool ls time                              # List tools
pfscan tool show time get_current_time           # Show tool schema
pfscan tool call time get_current_time --args '{}' # Call tool

📦 MCP Catalog

Discover and install MCP servers from the registry:

pfscan catalog search time                                    # Search
pfscan catalog view @modelcontextprotocol/server-time         # View details
pfscan catalog install @modelcontextprotocol/server-time --id time  # Install
pfscan catalog sources                                        # Manage sources

📈 Tool Usage Analysis

pfscan analyze                      # Analyze all tool usage
pfscan analyze --connector time     # Specific connector
pfscan analyze --verbose            # Detailed statistics

📝 Validation Plans

Create and run automated validation plans:

pfscan plans ls                    # List plans
pfscan plans add plan.yaml         # Add a plan
pfscan plans run --id myplan       # Execute plan
pfscan plans runs                  # View execution history

Command Reference

Main Commands
  view (v)        View recent events timeline (default)
  tree (t)        Show connector → session → RPC structure
  rpc             Inspect RPC call details
  summary         Show session summary and capabilities
  analyze         Analyze tool usage across sessions
  scan (s)        Run a new scan against MCP servers
  proxy           Run MCP proxy server
  serve           Protocol gateway HTTP server
  shell           Start interactive shell (REPL)
  monitor         Web monitor UI
  tool            List, inspect and call MCP tools
  catalog (cat)   Search and inspect MCP servers from registry
  registry        Local connector discovery
  runners         Manage package runners (npx, uvx)
  connectors      Manage MCP server connectors
  config (c)      Configuration management
  secrets         Secret management
  archive (a)     Data retention and cleanup
  doctor          Diagnose and fix issues
  status (st)     Show database and system status
  popl            Public Observable Proof Ledger management
  plans           Manage validation plans

A2A Agent Commands
  agent           A2A agent management (add, ls, scan)
  task            A2A task management (ls, show, cancel)

Ancillary Commands
  sessions        Manage scan sessions
  record          Record management commands
  log             View proxy logs

Run pfscan help <command> for details on any command.

Configuration

Config file location (OS-standard):

| Platform | Path | |----------|------| | Windows | %APPDATA%\proofscan\config.json | | macOS | ~/Library/Application Support/proofscan/config.json | | Linux | ~/.config/proofscan/config.json |

Example configuration:

{
  "version": 1,
  "connectors": [
    {
      "id": "time",
      "enabled": true,
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-time"]
      }
    }
  ],
  "retention": {
    "keep_last_sessions": 50,
    "raw_days": 7,
    "max_db_mb": 500
  }
}

Data Storage

~/.config/proofscan/
├── config.json                 # Configuration file
├── events.db                   # Sessions, events, RPC calls (prunable)
├── proofs.db                   # Immutable proof records (never pruned)
├── proxy-runtime-state.json    # Proxy state (if proxy used)
└── proxy-logs.jsonl            # Proxy logs (if proxy used)

Global Options

-c, --config <path>  Path to config file
--json               Output in JSON format
-v, --verbose        Verbose output
-h, --help           Display help
-V, --version        Show version

Use Cases

| Use Case | Description | |----------|-------------| | 🔍 Debug | See exactly what's happening in JSON-RPC communication | | 📊 Analyze | Track which tools are called and how often | | 🎯 Performance | Measure RPC latency and identify bottlenecks | | 🔐 Security | Review permission requests and data access | | 📝 Documentation | Generate public-safe logs for bug reports | | 🧪 Testing | Verify MCP server behavior and tool schemas | | 🎭 Integration | Aggregate multiple MCP servers via proxy |

Related Projects

• Model Context Protocol – Official MCP specification
• MCP Servers – Official server implementations

License

MIT

Support

• 📖 Documentation: See docs/ directory
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ by Proof of Protocol