The Usage server is the read-only window into the Organization's credit balance, usage history, and configured spending limits. An application uses it to display "how many credits do I have left," to itemize past activity, and to check whether a planned operation will trip a limit.

Everything here is read-only. Usage is recorded as a side effect of the work that consumes credits (LLM completions, image and media generation, git operations, etc.) — there's no tool here to create or modify a record.

Two flavors of visibility, decided by the calling user's role in the Organization:

 sees their own usage; an Owner sees the Organization's. Same tool, different shape, by role.

CharmIQ's billing model carries a few kinds of credits, each with different rules:

 returns each balance separately so your application can show them with the right framing. A user on a paid plan with PAYG top-up sees three meaningful numbers, not one.

. Display them with appropriate rounding for human consumption, but use the full precision when comparing or summing.

Two different shapes for two different questions:

Real-time counters may differ slightly from records aggregated over the same window — the timing isn't perfectly synchronized. For correctness, sum the records. For freshness, read the counters.

An application that's about to launch a potentially expensive job (a long multi-Charm chain, a Veo video generation) is well-advised to check 

 — Generation calls consume credits; check 

Query credit balance, usage history, and spending limits — read-only, role-gated by membership level.

Role	Sees
Regular member	Their own usage records and counters, plus Organization-scoped limits
Organization Owner	All members' records, all per-user counters, credit balances, system caps, billing status

Tool	What It Does
`get_usage_snapshot`	Real-time credit balances and usage counters (daily and monthly)
`list_usage_records`	Paginated list of usage events (debits and credits)
`get_usage_record`	Full details for a single usage record
`get_usage_limits`	Configured hard/soft limits and system caps

Type	Source	Reset
Plan Credits	Included with the Organization's plan	Resets per billing period
PAYG Credits	Purchased directly	Never reset, never expire
Overage Credits	Invoiced when usage exceeds plan with billing enabled	N/A — billed
BYOK	Bring-Your-Own-Key usage	Tracked but not billed by the platform

Usage MCP Server

Permission Model

Tools

The Credit System

Records and Counters

Limits

Patterns

Next Steps