---
title: Installation
description: Install and run the MCP Proxy.
---

## Install

### Homebrew (macOS, Linux)

```bash
brew install agent-receipts/tap/mcp-proxy
```

### Prebuilt binaries

Download a tarball for your platform (darwin/linux, amd64/arm64) from the [releases page](https://github.com/agent-receipts/ar/releases?q=mcp-proxy) and move `mcp-proxy` onto your `$PATH`.

### From source

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

```bash
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:

```bash
# bash / zsh
export PATH="$(go env GOPATH)/bin:$PATH"
```

```fish
# fish
fish_add_path (go env GOPATH)/bin
```

## 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):

```bash
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](/mcp-proxy/claude-code/), [Claude Desktop](/mcp-proxy/claude-desktop/), or [Codex](/mcp-proxy/codex/).

## 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](/mcp-proxy/approval-ui/) 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](/mcp-proxy/approval-ui/#opting-out-of-approval).

**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](/mcp-proxy/configuration/#-32002-errors-on-tool-calls) for how to distinguish the two sources.

## Standalone signing key

For production use, key management is handled by `agent-receipts-daemon` — see [Daemon Setup](/getting-started/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:

```bash
mcp-proxy init
```

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

```bash
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`):

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

## Next steps

- [Approval Server](/mcp-proxy/approval-ui/) — opt-in human-in-the-loop approval workflow
- [Configuration](/mcp-proxy/configuration/) for CLI flags, policy rules, redaction, and encryption
- [CLI Commands](/reference/cli-commands/) for querying and verifying the audit trail
