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

| Tool | Type | What it does | | -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | get_billing_summary | read · session | Your plan tier, its quota ceilings, and live usage against them (avatars + storage, agents, MCP calls, LLM calls) + headroom. | | query_usage | read · session | Metered usage rolled into an invoice statement for a period — per-action line items, totals, and reconciliation. | | export_billing_history | read · session | The same line items as a ready-to-save CSV payload (with a suggested filename and a parsed preview). | | get_receipt | read · session | One itemized receipt — per-charge by event_id (with settlement tx + explorer link) or a signed skill-purchase receipt by purchase_id. | | get_revenue | read · session | Earnings for the agents you own — gross/fee/net, per-skill and over time, plus creator-subscription income. | | get_fee_info | read · public | The current platform fee rate (fee_bps + fee_percent). Needs no session. |

Everything reads live state — usage, invoices, and earnings all 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_revenue — agent_id (UUID, optional — narrow to one agent), from / to (ISO-8601, default last 30 days), granularity (day | week | month, default day).

get_fee_info — none.

What you owe vs. what you earned

Two sides of the same account, two tools:

• "What did this cost me?" → query_usage / export_billing_history / get_receipt — metered charges, the period statement, and the receipt behind any single charge.
• "What did my agents make?" → get_revenue — gross/fee/net earnings, per-skill and over time, plus creator-subscription income.

get_billing_summary sits above both: 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".
• get_revenue earnings totals are in the token's atomic units (currency_mint / chain identify the token); creator-subscription income is reported separately in USD because it settles directly to your wallet, never mixing units with the withdrawable pool.
• reconciliation on the usage and revenue 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

| Variable | Required | Default | | ----------------------- | -------------------------------- | -------------------- | | THREE_WS_BASE | no | https://three.ws | | THREE_WS_TIMEOUT_MS | no | 20000 | | THREE_WS_SESSION | yes (all reads but get_fee_info) | — |

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