---
name: agent-cost-lens-mcp
description: See where your agent token money goes — and the caching fixes that recover it. Local sweep, local scrub, metadata-only upload — audit it yourself with preview_upload before anything is sent.
capabilities: [cost-analysis, cache-waste-detection, caching-advice, spend-reporting]
---

# Agent Cost Lens — MCP client

Two tools:
- **preview_upload** — shows what would be sent (a sample of the scrubbed
  records, plus every field name that travels). Sends nothing. Works with
  zero configuration.
- **analyze_costs** — sends that metadata to your Agent Cost Lens server and
  returns your spend, cache-hit rate, and what proper caching recovers
  (figures are simulated upper bounds, labeled as such).

## It names the fix
On API-log runs the report goes past measurement: a pattern catalog names your
specific cache-waste — uncached history (missing `cache_control` on a stable
prefix), cache churn (write premium with little read-back), volatile prefixes
(something early in the prompt changing per request). Where the arithmetic
supports a figure, it prices what fixing that pattern recovers, computed from
your own usage and labeled (simulated); where it does not — two of the four
patterns carry no dollar figure, volatile prefixes and one-shot workloads — the
report says so in as many words rather than inventing one. When a workload has
nothing left to recover, no pattern fires and the report names none — it shows
you the measurement and stops, instead of manufacturing a fix. The one case it
calls out by name is the one-shot workload: "caching can't help one-shot
workloads." An empty catalog is a first-class result, not a failure state.

## Export to a file (no server, no upload)
When you want every scrubbed record on disk — for a script of your own to
read — ask for them explicitly:

```
python3 -m acl_mcp.export --out records.jsonl [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--project FOLDER]
```

One `apilog-v1` record per line, built by the same code and the same salt as an
upload, so exported and uploaded rows carry the same pseudonyms. `--project`
narrows the sweep to one folder under `~/.claude/projects/`. The export path
imports nothing that can reach a network.

**What it puts on your disk, all of it.** Two files, not one:

- **the file you name** — the only output, and replaced atomically. While the
  write is in flight a transient `<out>.<rand>.part` sits beside it; that gets
  renamed over your file and is gone before the command returns.
- **`~/.config/agent-cost-lens/salt`** — 32 random bytes, created on the first
  run of a machine that has none, and only then; after that it is read, never
  rewritten. The salt is a file rather than a fresh random per run because that
  is what keeps a pseudonym *stable*: the same repo hashes to the same tag on
  your next run and on the upload path, which is the only reason an exported row
  and an uploaded row can be matched up. It stays on your machine.

Nothing else is written — no record store, no cache, no log.

## Privacy
Prompt text and code never leave your machine — the wire format has no field
for them. Repo and session names are HMAC-pseudonymized with a salt that
never leaves `~/.config/agent-cost-lens/salt`. Run preview_upload and read
the payload yourself; that output is the whole story.

## Setup
```json
{
  "mcpServers": {
    "agent-cost-lens": {
      "command": "acl-mcp",
      "env": {
        "LENS_SERVER_URL": "https://your-analyzer.example",
        "LENS_API_KEY": "acl_..."
      }
    }
  }
}
```
Install: `pip install <tarball>` (or `uvx --from <dir> acl-mcp`). Get a key
from the operator. `preview_upload` needs neither.