[!WARNING] This repository has been archived. Development has moved to the monorepo at agent-receipts/ar.

mcp-proxy

MCP proxy with action receipts, policy engine, and intent tracking

Audit, govern, and sign every AI agent action.

What it does

mcp-proxy sits between an MCP client (Claude, etc.) and an MCP server, transparently intercepting every tool call. For each call it:

Classifies the operation (read/write/delete/execute) and scores risk (0-100)
Evaluates policy rules (pass/flag/pause/block) with approval workflows
Groups related calls by temporal proximity (intent tracking)
Signs a cryptographic receipt (Ed25519, hash-chained, W3C Verifiable Credential)
Redacts sensitive data (JSON-aware + pattern-based) before storage
Stores everything in a local SQLite audit trail

Single binary. No external dependencies. Drop-in for any MCP server.

Install

go install github.com/agent-receipts/mcp-proxy/cmd/mcp-proxy@latest

Usage

As MCP proxy

# Wrap any MCP server
mcp-proxy node /path/to/mcp-server.js

# With options
mcp-proxy \
  --name github \
  --key private.pem \
  --taxonomy taxonomy.json \
  --rules rules.yaml \
  --issuer did:agent:my-proxy \
  --principal did:user:alice \
  node /path/to/github-mcp-server.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "github-audited": {
      "command": "mcp-proxy",
      "args": [
        "--name", "github",
        "node", "/path/to/github-mcp-server.js"
      ]
    }
  }
}

CLI subcommands

mcp-proxy list                          # List receipts
mcp-proxy list --risk high              # Filter by risk
mcp-proxy inspect <receipt-id>          # Show receipt details
mcp-proxy verify --key pub.pem <chain>  # Verify chain integrity
mcp-proxy export <chain-id>             # Export chain as JSON
mcp-proxy stats                         # Show statistics

Policy engine

Define rules in YAML:

rules:
  - name: block_destructive_ops
    description: Block high-risk delete operations
    enabled: true
    tool_pattern: "delete_*"
    min_risk_score: 70
    action: block

  - name: pause_high_risk
    description: Pause for approval when risk >= 50
    enabled: true
    min_risk_score: 50
    action: pause

Actions: pass (log only), flag (log + highlight), pause (wait for approval), block (reject).

When a tool call is paused, approve or deny via HTTP:

curl -X POST http://localhost:8080/api/tool-calls/{id}/approve
curl -X POST http://localhost:8080/api/tool-calls/{id}/deny

Paused calls auto-deny after 60 seconds (fail-safe).

Encryption

Set BEACON_ENCRYPTION_KEY to enable AES-256-GCM encryption at rest for sensitive audit data.

License

Apache 2.0

MCP Servers