Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

pecta-proxy is a CLI that spawns any MCP server as a subprocess, intercepts JSON-RPC tools/call responses over stdio, runs Pecta quality gates, and either forwards the original response or replaces it with a structured error if a gate fails. No changes to the MCP server are required. The proxy works in local-only mode without an API key, making it easy to evaluate gates before committing to cloud telemetry.
1

Run in local mode (no key required)

The fastest way to get started is to wrap an existing MCP server with no configuration at all. The proxy gates every tool response locally and writes decisions to ~/.pecta/logs/YYYY-MM-DD.jsonl.
npx pecta-proxy --verbose npx -y @modelcontextprotocol/server-filesystem /tmp
--verbose prints a one-line summary for each evaluation to stderr so you can see gate decisions in real time. Remove it in production.
2

Add cloud telemetry with --key

Get a publishable key (pk_live_...) from pecta.ai, then pass it via --key. Gates still run locally; results are batched and shipped asynchronously to the Pecta cloud, where they appear in your dashboard and feed into the agent’s reputation score.
npx pecta-proxy --key pk_live_xxx node my-mcp-server.js
Use a pk_live_ (publishable) key here, not a sk_live_ secret key. Publishable keys are safe to include in config files and process arguments that may appear in logs.
3

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and wrap your existing MCP server entry by prepending pecta-proxy to the command:
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "pecta-proxy",
        "--key", "pk_live_xxx",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"
      ]
    }
  }
}
Restart Claude Desktop. The proxy is now transparent — Claude interacts with the MCP server exactly as before, but every tools/call response passes through Pecta gates first.
4

Observe a blocked tool call

When a gate fails, the proxy replaces the MCP server’s response with a JSON-RPC error using code -32000. The upstream client (Claude Desktop, Cursor, etc.) receives the error as if the server had rejected the call itself.
{
  "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 log blocking decisions without actually blocking. This is the recommended way to evaluate gate behaviour in production before enabling enforcement.

​
CLI flags

FlagDefaultDescription
--key <key>nonePublishable Pecta key (pk_live_...) for cloud telemetry. Without it, the proxy gates locally and writes to ~/.pecta/logs/.
--dry-runoffLog every gate decision but always forward the original MCP response.
--verboseoffPrint a one-line summary per evaluation to stderr.
--timeout <ms>50Total gate budget in milliseconds per response.
--max-message-size <bytes>1048576Drop JSON-RPC messages larger than this (1 MB by default).
--agent-id <id>mcp-proxyAgent identifier reported to telemetry and used for reputation scoring.
Set --agent-id to a meaningful identifier such as cursor-filesystem-prod so you can track this agent’s reputation separately from others in your dashboard.

​
Install globally

If you run pecta-proxy frequently, install it globally to avoid the npx download on every invocation: 
npm install -g pecta-proxy
pecta-proxy --verbose npx -y @modelcontextprotocol/server-filesystem /tmp