Let your AI client ask the receipt.

For hosted team reports, use the Workspace MCP guide. The tools on this page read or sync local aibill state and do not grant Workspace access.

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 local MCP tool can approve or start an improvement test, apply a change, or record human approval — 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.