MCP Proxy

The MCP Proxy is a transparent stdin/stdout proxy that sits between an MCP client (Claude Desktop, Claude Code, etc.) and any MCP server. It intercepts every tool call and provides cryptographic audit trails, risk scoring, and policy enforcement — without modifying the server or client.

Repository: mcp-proxy/

Features

Risk scoring — scores every tool call 0-100 based on operation type, sensitive keywords, and patterns
Operation classification — classifies calls as read, write, delete, or execute by tool name
Action taxonomy — classifies tool calls using configurable taxonomy mappings, with a bundled config for GitHub MCP server tools
MCP prefix stripping — automatically strips mcp__<server>__ prefixes so receipts and classification use clean tool names
Policy enforcement — YAML rules engine with four actions: pass, flag, pause (approval required), and block
Approval workflows — HTTP endpoints for async approval of paused operations
Cryptographic receipts — Ed25519-signed W3C Verifiable Credentials, hash-chained per session
Issuer identity — receipts identify the AI agent, model, and operator via CLI flags
Intent tracking — groups related tool calls by temporal proximity
Data redaction — JSON-aware and pattern-based redaction of secrets before storage
Encryption at rest — optional AES-256-GCM encryption of audit data
Audit CLI — list, inspect, verify, export, and query receipts from the command line

How it works

MCP Client (Claude Desktop / Claude Code)
    |
    v
 mcp-proxy (stdin/stdout)
    |  - classify operation
    |  - score risk
    |  - evaluate policy rules
    |  - redact sensitive data
    |  - sign receipt
    |  - log to SQLite
    v
 MCP Server (any)

The proxy reads JSON-RPC messages on stdin, processes tools/call requests, forwards them to the wrapped server, and returns the response. Each tool call generates a signed Agent Receipt that is hash-chained into a tamper-evident audit log.

Quick start

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

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

# With configuration
mcp-proxy \
  -name github \
  -key private.pem \
  -rules rules.yaml \
  -taxonomy taxonomy.json \
  node /path/to/github-mcp-server.js

Claude Desktop integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "github-audited": {
      "command": "/Users/YOU/go/bin/mcp-proxy",
      "args": [
        "-name", "github",
        "-key", "/Users/YOU/.agent-receipts/github-proxy.pem",
        "-db", "/Users/YOU/.agent-receipts/audit.db",
        "-receipt-db", "/Users/YOU/.agent-receipts/receipts.db",
        "-issuer-name", "Claude Desktop",
        "-operator-id", "did:web:anthropic.com",
        "-operator-name", "Anthropic",
        "-taxonomy", "/Users/YOU/.agent-receipts/github_taxonomy.json",
        "/opt/homebrew/bin/mcp-server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Note: claude_desktop_config.json is not encrypted. Avoid committing it to version control, and prefer sourcing tokens from your OS keychain or a secret manager where possible.

Claude Code integration

Claude Code uses claude mcp add-json to register servers. Use --scope user to make the proxy available across all projects:

claude mcp add-json github-audited --scope user '{
  "command": "/Users/YOU/go/bin/mcp-proxy",
  "args": [
    "-name", "github",
    "-key", "/Users/YOU/.agent-receipts/github-proxy.pem",
    "-db", "/Users/YOU/.agent-receipts/audit.db",
    "-receipt-db", "/Users/YOU/.agent-receipts/receipts.db",
    "-http", "127.0.0.1:8081",
    "-issuer-name", "Claude Code",
    "-operator-id", "did:web:anthropic.com",
    "-operator-name", "Anthropic",
    "-taxonomy", "/Users/YOU/.agent-receipts/github_taxonomy.json",
    "/opt/homebrew/bin/mcp-server-github"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
  }
}'

Verify registration:

claude mcp list

See the Claude Code integration guide for a full walkthrough including project-scoped setup and .mcp.json configuration.

What receipts look like

Each tool call produces a signed W3C Verifiable Credential. Key fields shown (abbreviated — full receipts include @context, id, type, issuanceDate, and proof):

{
  "issuer": {
    "id": "did:agent:mcp-proxy",
    "name": "Claude Code",
    "operator": {
      "id": "did:web:anthropic.com",
      "name": "Anthropic"
    }
  },
  "credentialSubject": {
    "principal": { "id": "did:user:otto" },
    "action": {
      "type": "data.api.read",
      "tool_name": "get_issue",
      "risk_level": "low",
      "target": { "system": "github" }
    },
    "outcome": { "status": "success" },
    "chain": {
      "sequence": 1,
      "previous_receipt_hash": null,
      "chain_id": "9351bc33-..."
    }
  }
}

Receipts are Ed25519-signed, hash-chained per session, and stored in a local SQLite database. Use mcp-proxy list, mcp-proxy inspect, and mcp-proxy verify to query and validate them.

See Installation to get started, or Configuration for the full set of options.