three.ws Billing

@three-ws/billing-mcp

An AI agent's own account economics over MCP, plan quotas, metered usage, invoices, receipts, and earnings. Read-only and account-scoped.

A Model Context Protocol server that lets an AI agent self-serve its own account economics over stdio: how much of its plan quota is left, what its metered usage rolled up to this period, the line-item invoice and per-charge receipts behind every charge, and the earnings its agents have made, all without pulling in the human account owner.

Every read hits the live three.ws billing API: nothing is mocked. The account-scoped reads run against the account you own, resolved from your three.ws session. This server is read-only: it surfaces private billing data but never signs, charges, or moves funds.

Install

npm install @three-ws/billing-mcp

Or run with npx (no install):

npx @three-ws/billing-mcp

Quick start

Claude Code, one line:

claude mcp add billing -- npx -y @three-ws/billing-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{

"mcpServers": { "billing": { "command": "npx", "args": ["-y", "@three-ws/billing-mcp"], "env": { "THREE_WS_SESSION": " " } } } }

THREE_WS_SESSION is required for every read except the public fee rate, it's the value of the __Host-sid cookie from a signed-in three.ws browser session, and the API uses it to resolve your account and return only your data.

Inspect the surface with the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx @three-ws/billing-mcp

Tools

Everything reads live state: usage and invoices move between calls, so no tool is idempotent, and nothing here mutates anything.

Input parameters

`get_billing_summary`: none.

`query_usage`: period (YYYY-MM, optional), from / to (ISO-8601, optional; ignored when period is set). Defaults to the current UTC calendar month.

`export_billing_history`: period, from, to (same as query_usage), preview_rows (0-100, default 5, how many parsed rows to echo in preview; the full CSV is always returned).

`get_receipt`: exactly one of event_id (numeric, per-charge receipt) or purchase_id (UUID, signed skill-purchase receipt).

`get_fee_info`: none.

Examples

// get_billing_summary: plan ceilings and live usage against them

{}

{ "ok": true, "plan": "free", "quotas": { "max_avatars": 10, "max_bytes_per_avatar": 26214400, "max_total_bytes": 262144000, "mcp_calls_per_day": 1000 }, "usage": { "avatar_count": 1, "total_bytes": 1234540, "agent_count": 1, "mcp_calls_24h": 0, "llm_calls_month": 0 }, "remaining": { "avatars": 9, "total_bytes": 260909460, "mcp_calls_today": 1000 } }

// query_usage: the period statement (defaults to the current UTC month)

{}

{ "ok": true, "period_label": "2026-08", "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z" }, "line_item_count": 0, "line_items": [], "totals": { "charge_count": 0, "gross_atomics": "0", "fee_atomics": "0", "net_atomics": "0", "gross_usd": "0.00", "fee_usd": "0.00", "net_usd": "0.00", "currency": "USDC" }, "reconciliation": { "total": 0, "reconciled": 0, "unreconciled": 0, "all_reconciled": true } }

// export_billing_history: the same statement as a ready-to-save CSV

{ "preview_rows": 5 }

{ "ok": true, "filename": "three-ws-invoice-2026-08.csv", "content_type": "text/csv; charset=utf-8", "row_count": 1, "preview": [ { "action": "TOTAL", "count": "0", "gross_usd": "0.00", "fee_usd": "0.00" } ], "csv": "action,label,count,units,gross_usd,fee_usd,discount_bps\nTOTAL,,0,,0.00,0.00,\n" }

// get_fee_info: the one read that needs no session

{}

{ "ok": true, "fee_bps": 250, "fee_percent": "2.5" }

A quiet account reads like the statements above: zeroed totals with all_reconciled: true. That is the healthy empty state, not a failed call. Every read without THREE_WS_SESSION (except get_fee_info) fails loudly instead of returning empty data:

{ "ok": false, "error": "no_session", "status": 401,

"message": "/api/billing/summary is account-scoped and needs your three.ws session. …" }

What you owe

• "What did this cost me?" → query_usage / export_billing_history / get_receipt, metered charges, the period statement, and the receipt behind any single charge.

get_billing_summary sits above them: your plan, its quota ceilings, and how much headroom is left.

Money & units

• Charge amounts are in USDC atomics (6 decimals) alongside a human *_usd string, e.g. gross_atomics: "150000" is gross_usd: "0.15".
• reconciliation on the usage reads tells you whether every metered charge maps to a real on-chain settlement (all_reconciled, plus counts).

Requirements

• Node.js >= 20.
• Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

THREE_WS_SESSION is the value of the __Host-sid cookie from a signed-in three.ws browser session. Treat it like a password, it grants read access to your private billing data.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

Part of the three.ws SDK suite, 3D AI agents, on-chain identity, and agent payments.

Website · Changelog · GitHub