paperops

Observability control plane for Paper's MCP. A pass-through proxy that sits between your MCP clients and Paper's local server, metering, attributing, and live-streaming every tool call. Paper charges per MCP call but ships no usage meter — paperops is that meter.

Features

• Live tape — every MCP call as it happens: client, tool, file, status, latency, size. Sort it, filter it, slice it by file tabs.

• Call inspector — click any row: plain-language facts, a latency sparkline against recent calls of the same tool, and the raw request/response one click (and one copy button) away.

• Budgets — weekly quotas from Paper's real plans (free/pro), per-file and per-client limits, runaway-session alerts. Declarative JSON, hot-reloaded, warn-only.

• Timelapse — the canvas snapshots your agent already takes, turned into browsable checkpoints of the session.

• Passive by design — zero MCP calls of its own. The meter never spends what it measures.

• Private by design — payloads and snapshots live in memory only, the on-disk ledger is metadata, and the dashboard binds to localhost.

• Zero dependencies — one Bun process, one HTML file. bunx paperops and you're watching.

Related MCP server: MCPSpend

Run

bun dev
# paperops · proxy :29980/mcp → http://127.0.0.1:29979/mcp · dashboard http://127.0.0.1:29980/

Requires the Paper desktop app running (it serves the real MCP on 127.0.0.1:29979).

Wire your clients through it

This repo ships a project-scoped .mcp.json: open it with Claude Code and the paperops server is already wired through the proxy — approve it once and every call appears on the tape at http://127.0.0.1:29980/ in real time.

To observe sessions in other projects, point them at the proxy too:

claude mcp add --transport http paperops http://127.0.0.1:29980/mcp

Or copy the .mcp.json entry into that project.

What gets recorded

One JSONL line per call in ~/.paperops/ledger.jsonl:

{"id":42,"ts":"2026-07-27T21:01:26.357Z","session":"b5c06314-…","client":"claude-code","rpc":"tools/call","tool":"write_html","status":200,"ms":48.1,"argsBytes":2114,"resultBytes":880,"error":null}

• Attribution comes free: the proxy reads clientInfo.name from initialize payloads and tags every subsequent call in that session.

• The 7-day meter counts tools/call requests against your weekly quota — which comes from budgets.json (week, or the plan preset). It survives restarts by replaying the ledger.

• The ledger is an audit trail: the exact sequence of every call — names, timing, sizes, attribution. Call payloads live in memory only (privacy by design), so sessions can be audited from disk but not re-executed.

Budgets

~/.paperops/budgets.json — declarative limits, hot-reloaded on save:

{
  "plan": "pro",
  "budgets": [
    { "scope": "file", "match": "paperops", "limit": 2000, "note": "design project" },
    { "scope": "client", "match": "claude-code", "limit": 50000 }
  ]
}

• plan — "free" or "pro"; sets the weekly quota to Paper's official number (100 or 1M calls/week, per paper.design/pricing) and a sensible session alert (50 / 200 — a heavy design session measures ≈100 calls). Defaults to free: the Free user is the one a silent meter hurts most.

• week / sessionAlert — explicit overrides for the plan-derived values.

• budgets — one rule per line: scope (file or client), match (exact string — a file name or id, or a client name; no regex/glob), limit (weekly calls), optional note for humans. Matching by file name reads better but detaches if the file is renamed in Paper; ids survive renames.

States: ok → warning at 80% (chrome yellow) → exceeded (red), shown on the header meter, tab counts, and the budgets rail section. v1 warns, never blocks.

Config

Nothing Paper-specific lives in the proxy path — point PAPEROPS_TARGET at any streamable-HTTP MCP server and it meters that instead.

Known limitation: JSON-RPC batch requests pass through untouched but meter as a single request (no per-call accounting). No supported client sends batches today, and recent MCP revisions removed batching from the protocol.