> ## 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.

# Gate MCP tool responses with pecta-proxy CLI

> Gate MCP tool responses without touching server code. pecta-proxy runs locally with no key or with a publishable key for cloud telemetry and reputation.

`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.

<Steps>
  <Step title="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`.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Add cloud telemetry with --key">
    Get a publishable key (`pk_live_...`) from [pecta.ai](https://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.

    ```bash theme={null}
    npx pecta-proxy --key pk_live_xxx node my-mcp-server.js
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## CLI flags

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

<Tip>
  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.
</Tip>

## Install globally

If you run `pecta-proxy` frequently, install it globally to avoid the `npx` download on every invocation:

```bash theme={null}
npm install -g pecta-proxy
pecta-proxy --verbose npx -y @modelcontextprotocol/server-filesystem /tmp
```