MCP server TokenZero

TokenZero tools

Open-source tools from TokenZero, the independent ledger of record for AI spend (metering, attribution, budget control, audit).

• The receipt verifier (verifier/tokenzero-verify.mjs) checks a TokenZero receipt without trusting TokenZero: Ed25519 signature over canonical JSON, the savings-bucket math and the hash chain. Zero dependencies; library or CLI. The format is specified in docs/receipt-spec.md.

• @tokenzero/mcp is a stdio MCP server for Claude Code, Cursor, Windsurf and Cline: audit the open project for token waste (locally), price model alternatives, make request bodies cache-friendly.

• @tokenzero/cli connects a project to the ledger (through the gateway sensor) with no code changes, audits LLM token waste locally, shows usage and verifies signed savings receipts.

• The analyzer (src/audit-core.ts) is the static token-waste audit used by the CLI, the hosted repo audit and the PR cost-diff check. It runs entirely on your machine.

• The pricing table (src/pricing.ts) lists the list prices every estimate is computed from, versioned and dated.

Audit a project

npx -y @tokenzero/cli audit            # local, nothing is uploaded
npx -y @tokenzero/cli audit --json
npx -y @tokenzero/cli audit --fail-over 30   # CI gate: exit 1 above 30% recoverable
git diff origin/main | npx -y @tokenzero/cli audit --diff - --format markdown

Audits are static heuristics: they read code, not traffic. Numbers are estimates at list prices; verified savings come from the gateway's signed ledger once requests flow through it.

What it looks for:

• large static prompts sent without caching directives (Anthropic cache_control, OpenAI prefix stability)
• prompt templates defined away from their call sites with no caching anywhere
• frontier models on prompts that read like extraction or classification
• LLM calls inside loops (Batch API or shared-prefix caching candidates)
• unpriced or retired model ids

Library and SDK repositories are detected and their findings downgraded, since their call sites pass through whatever the caller chooses.

Check every pull request (GitHub Action)

# .github/workflows/tokenzero.yml
name: TokenZero cost check
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  cost-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: tokenzero-ai/tokenzero/action@v0

One comment per PR, updated on every push; nothing leaves the runner. See action/README.md for inputs and outputs.

Use it from a coding agent (MCP)

claude mcp add tokenzero -- npx -y @tokenzero/mcp          # Claude Code

{ "mcpServers": { "tokenzero": { "command": "npx", "args": ["-y", "@tokenzero/mcp"] } } }

audit_repo_token_waste and calculate_model_arbitrage run entirely on your machine. optimize_prompt_payload sends the request body you give it to the TokenZero service (https://tokenzero.sh unless TOKENZERO_URL is set), so do not put secrets in it.

Connect a project to the gateway

npx -y @tokenzero/cli init

init audits locally, creates a workspace, and (with your consent) adds OPENAI_BASE_URL / ANTHROPIC_BASE_URL to .env. Your provider keys pass through untouched and are never stored.

Authentication: send the workspace key as the X-TokenZero-Key header (recommended). For zero-code setups the CLI can also embed it in the base URL (/w/<key>/v1); treat such URLs as secrets and use tokenzero rotate-key if one leaks.

Develop

npm install
npm run build      # bundles cli/bin/tokenzero.mjs (single file, no runtime deps)
npm test

License: Apache-2.0 · support@tokenzero.sh