three.ws Billing

[three.ws]

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

[npm] [license] [node] [MCP Registry] [three.ws]

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": "<your __Host-sid cookie>"			}		}	}}

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}