three.ws Billing

io.github.nirholasPublished by GitHub account nirholasv0.1.3Updated Nov 1, 2026

An agent's account economics — plan quotas, metered usage, invoices, receipts, and earnings.

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Read-only MCP server that lets an AI agent check its own three.ws billing: plan quotas, metered usage, invoices, receipts and earnings.

What you can do
  • Read plan tier, quota ceilings and live usage with remaining headroom
  • Query metered usage for a period as an invoice statement with line items, totals and reconciliation
  • Export the same statement as a ready-to-save CSV payload with a preview
  • Fetch a single itemized receipt by charge event ID or signed skill-purchase ID
  • Read the current public platform fee rate without a session
When to use it
Use it when an agent needs to answer questions about its own three.ws account costs, such as what a period cost, how much quota is left, or what a specific charge was for, without involving the human account owner.
Requirements
Runs locally over stdio via npx, so Node.js 20 or newer is needed. Network access to the three.ws API (or a custom THREE_WS_BASE). A required THREE_WS_SESSION secret, the value of the __Host-sid cookie from a signed-in three.ws browser session, for every read except the public fee rate. Optional THREE_WS_TIMEOUT_MS.
Before you install
THREE_WS_SESSION grants read access to private billing data and should be treated like a password; it is passed as an environment variable. All account-scoped reads return only the account resolved from that session. The server is read-only and never signs, charges or moves funds, but it does send requests to the live three.ws API. Usage and invoices change between calls, so results are not idempotent.

Installation

In SourceWeft

  1. Open three.ws Billing in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[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

bash
npm install @three-ws/billing-mcp

Or run with npx (no install):

bash
npx @three-ws/billing-mcp

Quick start

Claude Code, one line:

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

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

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:

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

Tools

ToolTypeWhat it does
get_billing_summaryread · sessionYour plan tier, its quota ceilings, and live usage against them (avatars + storage, agents, MCP calls, LLM calls) + headroom.
query_usageread · sessionMetered usage rolled into an invoice statement for a period, per-action line items, totals, and reconciliation.
export_billing_historyread · sessionThe same line items as a ready-to-save CSV payload (with a suggested filename and a parsed preview).
get_receiptread · sessionOne itemized receipt, per-charge by event_id (with settlement tx + explorer link) or a signed skill-purchase receipt by purchase_id.
get_fee_inforead · publicThe current platform fee rate (fee_bps + fee_percent). Needs no session.

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

jsonc
// 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 }}
jsonc
// 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 }}
jsonc
// 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"}
jsonc
// 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:

jsonc
{ "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

VariableRequiredDefault
THREE_WS_BASEnohttps://three.ws
THREE_WS_TIMEOUT_MSno20000
THREE_WS_SESSIONyes (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

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

Source: packages/billing-mcp/README.md at commit c8f2cde

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.3LatestOct 10, 2026
  2. v0.1.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts