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 exactly what would be sent (scrubbed usage metadata: token counts, model IDs, dates, pseudonymous tags). 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).

Related MCP server: Azure FinOps MCP Server

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 the same scrubbed records 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

{
  "mcpServers": {
    "agent-cost-lens": {
      "command": "acl-mcp",
      "env": {
        "LENS_SERVER_URL": "https://your-analyzer.example",
        "LENS_API_KEY": "acl_..."
      }
    }
  }
}

Install

The client is served from the site, not from PyPI — the name agent-cost-lens-mcp is not registered on PyPI, so a bare pip install agent-cost-lens-mcp will fail with "No matching distribution found". Install from the download endpoint:

pip install "agent-cost-lens-mcp @ https://lens.r-lattice.com/download"

That endpoint always serves the current client — 1.5.2 as of this review. It is not pinned, so it will hand you whatever is current at the time you run it; check pyproject.toml in this repo to see which client version this snapshot documents. uvx --from <dir> acl-mcp works against a local checkout.

If you installed client 1.5.0, reinstall. 1.5.0 could not start: it declared mcp>=1.0 with no upper bound, and mcp 2.x renamed the class acl_mcp/server.py imports, so the install succeeded and acl-mcp then died with ModuleNotFoundError. The dependency now reads mcp>=1.2,<2 — both edges load-bearing, because mcp 1.0.0 through 1.1.3 carry no mcp.server.fastmcp module either. Confirm what you have with:

pip show agent-cost-lens-mcp

Get an API key from the operator. preview_upload needs neither a key nor a server.

Reviewed 26 August 2026 against client 1.5.2. Every claim on this page was checked against the code in this snapshot, not against an earlier release, and the two disclosure claims — that preview_upload "shows exactly what would be sent" and that "that output is the whole story" — were checked by executing it, at limit=0 as well as at a normal limit.

Said precisely, because this is the one page where precision is the product: the preview's field line names every leaf path in the records, which is what _record_fields is computed over. Three payload-level paths sit outside that line by construction and are disclosed by two other lines instead — schema in the header, and plan.name / plan.monthly_cost in the "Plan sent as billing context" line, which print their values rather than their dotted paths. Measured on a payload exercising every branch of to_record: 16 leaf paths travel with a plan configured — 13 named by the field line, 3 by the header and plan lines — and 14 without one, the same 13 plus schema. Nothing travels unnamed in either case. What is still open is the class, not an instance: a brand-new top-level payload key would travel unshown, because the field line cannot see that level. See CHANGELOG.md under 1.8.6.

The 1.5.0 client did not meet the disclosure bar at all; see releases/v1.8.5.md.