pecta-proxy

Wrap any MCP server with quality gates that block dangerous tool calls before they reach the user.

pecta-proxy spawns an MCP server as a subprocess, intercepts every JSON-RPC tools/call response, runs Pecta gates over it, and either forwards the original response or replaces it with a -32000 error if a gate fails.

Install

npx pecta-proxy <command> [args...]

Or install globally:

npm install -g pecta-proxy

Quickstart — local mode (no key required)

npx pecta-proxy --verbose npx -y @modelcontextprotocol/server-filesystem /tmp

When a tool call returns an rm -rf or path-traversal payload, the proxy replaces the response with a structured error and logs the decision to ~/.pecta/logs/YYYY-MM-DD.jsonl.

With cloud telemetry

Get a publishable key from pecta.ai (or pnpm --filter @pecta/api admin issue-key if you're self-hosting), then:

npx pecta-proxy --key pk_live_xxx node my-mcp-server.js

Evaluations show up in your dashboard at dashboard.pecta.ai and feed into the agent's portable reputation score.

Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "pecta-proxy",
        "--key", "pk_live_xxx",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"
      ]
    }
  }
}

Flags

| Flag | Default | Description | |------|---------|-------------| | --key <key> | none | Publishable Pecta key for cloud telemetry. Without it, the proxy still gates locally and writes to ~/.pecta/logs/. | | --dry-run | off | Log every gate decision but always forward the original response. | | --verbose | off | Print one-line summary per evaluation to stderr. | | --timeout <ms> | 50 | Total gate budget per response. | | --max-message-size <bytes> | 1048576 | Drop JSON-RPC messages larger than this. | | --agent-id <id> | mcp-proxy | Agent identifier reported to telemetry. |

How blocking works

When gates fail, the proxy returns a JSON-RPC error to the upstream client:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32000,
    "message": "pecta: tool call blocked by quality gate",
    "data": { "gates": [{ "name": "filesystem", "reason": "destructive rm command detected" }] }
  }
}

Use --dry-run to observe blocking decisions in production before flipping them on.

License

Apache-2.0