Skip to main content
Glama
r-lattice

agent-cost-lens-mcp

by r-lattice
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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).

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 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

{
  "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.

Available Tools

2 tools
analyze_costsA

Analyze your Claude Code / Anthropic API token spend. Sweeps your local transcripts (or apilog JSONL files via apilog glob), scrubs identifiers on your machine, sends usage metadata only to your configured Agent Cost Lens server, and returns the cost summary with recoverable savings. Dates are YYYY-MM-DD. Use preview_upload first to audit what gets sent.

ParametersJSON Schema
NameRequiredDescriptionDefault
sinceNo
untilNo
apilogNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and performs admirably. It discloses that the tool sweeps local transcripts, scrubs identifiers on the machine, sends only usage metadata to a configured server, and returns recoverable savings—key behavioral and privacy-relevant traits beyond what the schema shows.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: one sentence states the core purpose, a second explains the operational flow, and the final sentence gives the date format and the prerequisite audit step. No sentences are wasted, and the most important context is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with three optional params, an output schema, and one sibling, the description provides comprehensive context: data sources, local processing, network transfer, return value, date format, and a safety instruction to preview first. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does by clarifying that 'since' and 'until' are dates in YYYY-MM-DD format and that 'apilog' is a glob for JSONL files. It doesn't explain default semantics when these optional params are omitted, but it adds meaningful meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific verb and resource: 'Analyze your Claude Code / Anthropic API token spend.' It then details the full workflow (sweeping transcripts, scrubbing identifiers, sending only usage metadata, returning a cost summary), making the tool's purpose concrete and distinguishable from the sibling preview_upload by framing preview_upload as a preliminary audit step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context, including the date format (YYYY-MM-DD) and an explicit sequencing instruction: 'Use preview_upload first to audit what gets sent.' It stops short of describing when not to use this tool or alternative conditions, but the guidance is sufficient for an agent to know when and how to proceed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_uploadA

Show exactly what analyze_costs WOULD upload — the scrubbed records, nothing else. Sends nothing; needs no key. This is the audit step.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
sinceNo
untilNo
apilogNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by disclosing two key behaviors: it sends nothing and requires no key. It also scopes the result to 'the scrubbed records, nothing else.' It does not mention default limits or filtering behavior, but the output schema covers the return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences with no filler. It front-loads the core purpose, immediately states the safety-relevant behavior, and closes with the tool's role. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no annotations and no parameter descriptions in the schema, so the parameter semantics gap is significant. The description covers purpose and safety well but leaves the agent unable to correctly populate apilog or understand how since/until/limit shape the output. The presence of an output schema only partially compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not explain any of the four parameters: limit, since, until, and apilog. While 'since' and 'until' are inferable as date bounds, 'apilog' remains opaque and there is no detail about how limit or the time filters affect the preview. The description only indirectly suggests these mirror analyze_costs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Show') and a precise object ('what analyze_costs WOULD upload — the scrubbed records, nothing else'). It clearly differentiates this preview tool from the actual upload tool, analyze_costs, and reinforces the purpose by calling it 'the audit step.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description names analyze_costs as the related upload action, states that this tool sends nothing and needs no key, and labels itself as the audit step. This makes the intended pre-upload verification use case reasonably clear, though it does not explicitly say 'use this before analyze_costs' or list exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.5.2
    • First observedanalyze_costs
    • First observedpreview_upload
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: preview_upload is a read-only audit step showing exactly what would be sent, while analyze_costs performs the actual sweep, upload, and summary. There is no meaningful overlap in their purposes.

Naming Consistency5/5

Both tool names follow a consistent verb_noun snake_case pattern: analyze_costs and preview_upload. The naming convention is uniform and predictable.

Tool Count4/5

Only two tools exist, which is slightly below the typical 3-15 range, but the domain is narrow and each tool earns its place: one main analysis/upload action and one preflight audit step. The count feels reasonable for the server's purpose.

Completeness5/5

The workflow is complete for the stated purpose: preview_upload covers the audit side and analyze_costs covers the actual analysis and upload. There are no obvious dead ends or missing operations within this narrow cost-analysis domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers