CLI Commands

The MCP Proxy includes subcommands for querying and verifying the audit trail.

`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 read_file          # filter by action type
mcp-proxy list -chain <chain-id>          # filter by chain
mcp-proxy list -limit 100                 # limit results
mcp-proxy list -json                      # JSON output

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
`-receipt-db`	Receipt store path (default: `receipts.db`)

Example output

$ mcp-proxy list
ID                                       ACTION                 RISK   STATUS   ISSUER         OPERATOR               TIMESTAMP
---
urn:receipt:58b9c7ff-cbed-45ed-a5bd-2... read                   low    success  codex          did:web:openai.com     2026-04-15T00:06:48Z
urn:receipt:3384715f-d633-4031-b96f-c... read                   low    success  codex          did:web:openai.com     2026-04-15T00:06:26Z
urn:receipt:c2e7b34f-04b2-42d1-a2f5-5... write                  medium success  Claude Code    did:web:anthropic.com  2026-04-15T00:01:39Z
urn:receipt:ccf92d30-8369-411d-af29-d... read                   low    success                                        2026-04-14T23:56:09Z
urn:receipt:ccc6860a-f1b5-4e2f-b3ea-a... read                   low    success  Claude Code    did:web:anthropic.com  2026-04-14T23:54:09Z

50 receipts

ISSUER is the agent name set via --name; OPERATOR is the operator DID set via --operator. Both are empty when the proxy is run without those flags.

`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: `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: `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: `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: `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: `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 -db ~/.agent-receipts/audit.db
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.