Skip to content
Agent Receipts

Installation

Install

Section titled “Install”

Homebrew (macOS, Linux)

Section titled “Homebrew (macOS, Linux)”
Terminal window
brew install agent-receipts/tap/mcp-proxy

Prebuilt binaries

Section titled “Prebuilt binaries”

Download a tarball for your platform (darwin/linux, amd64/arm64) from the releases page and move mcp-proxy onto your $PATH.

From source

Section titled “From source”
Terminal window
go install github.com/agent-receipts/ar/mcp-proxy/cmd/mcp-proxy@latest

Requires Go 1.26+. No CGO or external C libraries — the proxy uses pure Go SQLite.

Verify installation

Section titled “Verify installation”
Terminal window
mcp-proxy -version

If mcp-proxy isn’t found after go install (bash/zsh say command not found; fish says Unknown command), the Go bin directory isn’t on your $PATH. go install writes binaries to $GOBIN when it’s set, otherwise to $(go env GOPATH)/bin (usually ~/go/bin). Add whichever applies to your shell profile:

Terminal window
# bash / zsh
export PATH="$(go env GOPATH)/bin:$PATH"
Terminal window
# fish
fish_add_path (go env GOPATH)/bin

Basic usage

Section titled “Basic usage”

Wrap any MCP server by passing its command as arguments. For a quick smoke test, use the official filesystem MCP server (requires Node.js/npx — if you don’t have it, substitute any MCP server command you already have):

Terminal window
mcp-proxy npx -y @modelcontextprotocol/server-filesystem ~/Documents

The proxy intercepts stdin/stdout, logs every tool call, and forwards messages transparently. It always signs receipts locally — with -key if provided, or an ephemeral Ed25519 key pair otherwise. Separately, daemon forwarding sends a copy of each event to agent-receipts-daemon via the --socket flag (defaults to the platform socket path; set --socket="" to disable). Press Ctrl-C to stop.

For wiring the proxy into an actual client, jump to Claude Code, Claude Desktop, or Codex.

Approval server (opt-in)

Section titled “Approval server (opt-in)”

The default policy contains pause_high_risk (min_risk_score: 50), but the approval listener is off by default. A paused call without a listener configured fails immediately with JSON-RPC code -32003 (no approver configured…) — a fast, obvious failure rather than a 60-second timeout.

Most GitHub MCP tools don’t reach the threshold — create_pull_request scores 20, merge_pull_request scores 10, reads score 0. Combinations that actually cross 50: write + sensitive keyword (create_token = 50, update_auth_config = 70), delete + sensitive (delete_credential = 70), delete + config (delete_config = 60), execute + SQL-no-WHERE (60). Plain writes, plain deletes (40), update_config alone (40), and sensitive-keyword reads like get_token (30) do not pause.

If you want human-in-the-loop approvals: this section is for you. Pass -http 127.0.0.1:<port> to start the listener, then run an approver against it. The dedicated Approval Server page documents the HTTP routes (POST /api/tool-calls/{id}/approve and /deny) and shows a minimal shell approver.

If you don’t want approvals at all: omit -http (the default) and paused calls will fail fast. To prevent pausing entirely, load a custom -rules YAML with no pause or block rules — see opting out.

Seeing -32002 on a tool that shouldn’t pause? It’s most likely client-side denial by the MCP client (e.g. Claude Code), not the proxy. See the -32002 troubleshooting entry for how to distinguish the two sources.

Standalone signing key

Section titled “Standalone signing key”

For production use, key management is handled by agent-receipts-daemon — see Daemon Setup. The instructions below are for standalone use (no daemon), where the proxy holds the signing key directly.

mcp-proxy init does everything in one step: creates ~/.agent-receipts/, generates an Ed25519 keypair with correct permissions, initialises the receipt database, and prints a ready-to-paste claude_desktop_config.json snippet:

Terminal window
mcp-proxy init

Use --name to label a specific proxy instance (the name appears in the config snippet key and in the key filename):

Terminal window
mcp-proxy init --name github
# creates ~/.agent-receipts/github.pem (0600) and ~/.agent-receipts/github.pem.pub

Re-running init is safe — it warns and skips key generation if the files already exist. Pass --force to regenerate.

Then run the proxy with the generated key (substitute your instance name if you used --name):

Terminal window
mcp-proxy -key ~/.agent-receipts/default.pem npx -y @modelcontextprotocol/server-filesystem ~/Documents

Next steps

Section titled “Next steps”