CLI Commands

This page covers the mcp-proxy audit subcommands and the agent-receipts-hook PostToolUse hook binary.

The default -db and -receipt-db paths shown below resolve via Go’s os.UserHomeDir(). On Unix and macOS this is $HOME; on Windows this uses the OS user home directory, typically %USERPROFILE%.

`mcp-proxy -version`

Print the version and exit.

mcp-proxy -version
# mcp-proxy vX.Y.Z

`mcp-proxy list`

List receipts from the audit store. Results are sorted newest first — the most recent receipts appear at the top. Default limit is 50.

mcp-proxy list                            # latest 50 receipts, newest first
mcp-proxy list -risk high                 # filter by risk level
mcp-proxy list -action data.api.read      # filter by action type (taxonomy value)
mcp-proxy list -chain <chain-id>          # filter by chain
mcp-proxy list -limit 100                 # limit results
mcp-proxy list -json                      # JSON output
mcp-proxy list -f                         # tail-like: stream new receipts live
mcp-proxy list --follow --interval 1s     # custom poll interval

Flag	Description
`-risk`	Filter by risk level: `low`, `medium`, `high`, `critical`
`-action`	Filter by action type
`-chain`	Filter by chain ID
`-limit`	Maximum number of receipts to return (default: `50`)
`-json`	Output as JSON (NDJSON — one object per line — in `--follow` mode)
`-follow`, `-f`	After the initial listing, keep polling and stream new receipts as they are inserted (`tail -f`-style). Exit with `Ctrl-C`. In `--follow` mode, the startup batch is printed in chronological order (oldest → newest) so it reads continuously with the streamed tail.
`-interval`	Poll interval in `--follow` mode (default: `500ms`)
`-receipt-db`	Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`)

Example output

$ mcp-proxy list
ID                     SERVER         TOOL                           ACTION                 RISK     STATUS   TIMESTAMP
---
urn:receipt:b4b430f9... atlassian      getJiraIssue                   data.api.read          low      success  2026-04-24T02:05:19Z
urn:receipt:32506b71... atlassian      searchJiraIssuesUsingJql       data.api.read          low      success  2026-04-24T01:56:12Z
urn:receipt:f5da030f... atlassian      getAccessibleAtlassianResou... data.api.read          low      success  2026-04-24T01:56:06Z
urn:receipt:a125fd30... github         list_pull_requests             data.api.read          low      success  2026-04-24T01:44:20Z
urn:receipt:67fede57... github         add_reply_to_pull_reques...    data.api.write         medium   success  2026-04-24T00:51:57Z
urn:receipt:013bfc43... github         request_copilot_review         data.api.write         medium   success  2026-04-24T00:43:40Z
urn:receipt:7ae4f1b2... github         issue_write                    data.api.write         medium   success  2026-04-24T00:19:35Z
urn:receipt:d52ba1fd... github         issue_write                    data.api.write         medium   success  2026-04-24T00:19:25Z

8 receipts

SERVER identifies which MCP server handled the call. It comes from the -name flag, defaulting to the wrapped command’s basename if -name is omitted. TOOL is the raw tool name (truncated at 30 characters). When running multiple proxied servers simultaneously — for example GitHub and Atlassian — the SERVER column is how you tell their receipts apart at a glance.

The -action filter matches the ACTION column (taxonomy type, e.g. data.api.read), not the TOOL column. Issuer and operator identity isn’t shown in the tabular view — use mcp-proxy list -json to see it.

`mcp-proxy inspect`

Show details for a single receipt.

mcp-proxy inspect <receipt-id>
mcp-proxy inspect -key public.pem <receipt-id>   # verify signature

Flag	Description
`-key`	Public key PEM file to verify the receipt signature
`-receipt-db`	Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`)

`mcp-proxy verify`

Verify the integrity of a receipt chain — checks signatures, hash linkage, and sequence numbers.

mcp-proxy verify -key public.pem <chain-id>

Flag	Description
`-key`	Public key PEM file (required)
`-receipt-db`	Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`)

`mcp-proxy export`

Export a receipt chain as JSON.

mcp-proxy export <chain-id>
mcp-proxy export <chain-id> > chain.json

Flag	Description
`-receipt-db`	Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`)

`mcp-proxy stats`

Show aggregate statistics about the audit store.

mcp-proxy stats
mcp-proxy stats -json

Flag	Description
`-json`	Output as JSON
`-receipt-db`	Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`)

`mcp-proxy timing`

Show per-tool timing breakdown from the audit database. Reports average phase durations (policy evaluation, approval wait, upstream call, receipt signing) and p50/p95/p99 percentiles.

mcp-proxy timing                              # all sessions
mcp-proxy timing -session <session-id>        # filter by session
mcp-proxy timing -json                        # JSON output
mcp-proxy timing -limit 10                    # top 10 tools

Flag	Description
`-db`	Audit database path (default: `$HOME/.local/share/agent-receipts/audit.db`)
`-session`	Filter by session ID
`-limit`	Maximum number of tools to show (default: `20`)
`-json`	Output as JSON

Example output

$ mcp-proxy timing
Tool call timing (73 calls)

Per-tool averages:
TOOL                            COUNT UPSTREAM(us) POLICY(us) RECEIPT(us)  APPROVAL(us)  TOTAL(ms)
get_file_contents                  21            -          -           -             -        679
create_or_update_file              15            -          -           -             -       1162
search_issues                       6       747952          2         468             -        790
create_issue                        5            -          -           -             -       3742
create_branch                       5            -          -           -             -       1123

Percentiles:
PHASE                  p50        p95        p99
upstream            715744     946737     946737 (us)
policy_eval              2          5          5 (us)
receipt_sign           830       2420       2420 (us)
duration_ms            708       2489      16230 (ms)

Columns with - indicate tool calls recorded before timing instrumentation was added. New calls will populate all phase columns automatically.

The data shows that for a GitHub MCP server, upstream API latency dominates (about 716-947ms based on the upstream percentiles shown), while policy evaluation (2-5us) and receipt signing (0.8-2.4ms) add negligible overhead.

`mcp-proxy doctor`

Diagnose proxy configuration: load and validate the policy rules file, summarise enabled rules by action (pause, block, flag), and optionally probe an approver URL for reachability.

mcp-proxy doctor                                    # validate built-in defaults
mcp-proxy doctor -rules /path/to/rules.yaml         # validate a custom rules file
mcp-proxy doctor -approver http://127.0.0.1:7778    # probe an approver URL
mcp-proxy doctor -json                              # JSON output

Flag	Description
`-rules`	Policy rules YAML to validate (default: built-in)
`-approver`	Approver URL to probe for reachability (default: none)
`-json`	Output as JSON

Exit codes: 0 if the configuration is healthy; 1 if any issues are reported; 2 on flag/usage errors.

`mcp-proxy init`

One-command setup: creates ~/.local/share/agent-receipts/, generates an Ed25519 signing keypair with correct permissions (private key 0600, public key 0644), initialises the receipt database, and prints a claude_desktop_config.json snippet to stdout.

Safe to re-run — warns and skips key generation if files already exist (use -force to overwrite).

mcp-proxy init                              # generate keys for the "default" instance
mcp-proxy init -name github                 # custom instance name
mcp-proxy init -no-approval                 # omit -http from the printed snippet
mcp-proxy init -http-port 9000              # custom approval listener port in snippet
mcp-proxy init -force                       # overwrite existing key files

Flag	Description
`-name`	Name for this proxy instance, used in filenames and the config snippet (default: `default`)
`-no-approval`	Omit `-http` from the printed config snippet (no approval server)
`-http-port`	Approval listener port written into the config snippet (default: `7778`)
`-force`	Overwrite existing key files

Exit codes: 0 on success; 1 on setup errors (home directory resolve, key write, DB init); 2 on invalid arguments (out-of-range -http-port, invalid -name) or flag/usage errors.

`mcp-proxy audit-secrets`

Scan the audit database for values that match any built-in or custom redaction pattern. Useful after upgrading the proxy, adding new patterns, or as a periodic check that redaction is working as intended.

mcp-proxy audit-secrets                                       # scan with built-in patterns
mcp-proxy audit-secrets -redact-patterns custom.yaml          # also scan custom patterns
mcp-proxy audit-secrets -db /path/to/audit.db                 # specify audit DB path

Flag	Description
`-db`	Audit database path (default: `$HOME/.local/share/agent-receipts/audit.db`)
`-redact-patterns`	YAML file with additional patterns to scan for

If the database was encrypted at rest (proxy launched with BEACON_ENCRYPTION_KEY), set the same env var before running so the scanner can decrypt. Without the key, encrypted rows are reported as encrypted-no-key and counted as hits.

Output format — one line per match:

messages col=raw row=42 pattern=github_token
tool_calls col=arguments row=51 json-key=password
tool_calls col=result row=78 decrypt-error

The scanner reads messages.raw (full JSON-RPC payloads) and tool_calls.arguments / tool_calls.result / tool_calls.error — the columns where redaction is applied at write time.

Exit codes: 0 if no matches found; 1 if one or more matches found; 2 on error.

If matches are found, the raw token values are already in the database. Because the audit log is append-only, the recommended action is to rotate the secret and consider the old value compromised.

`agent-receipts-hook`

Short-lived PostToolUse hook binary that captures native host tool calls and forwards them to agent-receipts-daemon. Invoked automatically by agent runtimes that support PostToolUse hooks — not meant to be run interactively.

agent-receipts-hook [--format=<name>]

Flag	Description
`--format`	Force a specific input format (default: auto-detected from environment variables). Currently supported: `claude-code`.

Exit behaviour: Always exits 0. Emit failures (daemon not running, socket missing, malformed frame) are dropped silently — the hook never blocks the agent.

Auto-detection: When --format is omitted, the binary inspects environment variables to identify the calling runtime. CLAUDE_SESSION_ID set → claude-code format.

See Hook: Claude Code for wiring instructions.