Let your AI client ask the receipt.

Codex

codex mcp add aibill -- npx --yes --package @agent-finops/mcp@latest ai-spend-mcp
codex mcp list

Claude Code

claude mcp add --scope user aibill -- npx --yes --package @agent-finops/mcp@latest ai-spend-mcp
claude mcp list

Cursor or another stdio client

{
  "mcpServers": {
    "aibill": {
      "command": "npx",
      "args": ["--yes", "--package", "@agent-finops/mcp@latest", "ai-spend-mcp"]
    }
  }
}

Use ~/.cursor/mcp.json for all Cursor projects or .cursor/mcp.json for one project. Other clients use the same command and arguments at their documented local stdio configuration path.

Each scan/sync tool may write local aibill state; sync_provider_spend also contacts the selected provider API. The get, list, draft, and recommendation tools are read-only, and no MCP tool can approve, start, apply, or record anything — approval exists only as the word APPROVE typed by the human in their own terminal. recommend_cuts can return an evidence gap or observed exposure instead of a cut; the name remains for compatibility.

Use aibill to sync my local coding-agent evidence for this project.
Then show the spend report, source status, Context Health, and one
evidence-constrained next action. Keep billed cost, API-equivalent value,
subscription context, and missing evidence separate.

1. Call sync_local_agent_spend with a specific absolute project path.
2. Read get_spend_report and list_sources.
3. Ask for get_context_health or get_usage_glance only when that decision surface helps.
4. Let the client draft a token test with draft_improve_command, then run the composed npx aibill improve --draft … yourself — approval and the quality-gated result stay in your terminal.

With no synced state, get_spend_report returns no_state, zero rows, a null financial headline, and exact next steps. Sample rows appear only after an explicit scan_ai_spend(sample=true) request.

• State tools require a specific absolute project path; home, filesystem, and system roots are refused.
• Raw provider keys are rejected. Provider tools accept an inherited env:NAME reference.
• Provider syncs are read-only against the selected provider API.
• This MCP server sends no telemetry and does not upload transcript contents.
• The selected structured tool result is returned to the invoking AI client and then follows that client’s data policy.
• A project cannot declare its own connected totals trusted; a separate hash-only local receipt binds trusted provider state to this machine.

Tools do not appear

Run the exact npx server command in a terminal, confirm Node 22+, restart the client, and verify that it supports local stdio MCP.

Provider returns 401 or 403

Use an organization/admin billing-read credential rather than a normal inference API key.

A path is refused

Select one project directory. Broad-root refusal is intentional prompt-injection protection.

Report says no_state

Run a local or provider sync for real evidence. No zero-dollar total or sample rows were inferred; sample data requires an explicit demo request.