Agent Billing Primitives (Dirtsmith)
Usage metering, spend cap (reserve before pay), lease lock, semaphore, heartbeat for agents. Free tr
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"mcp-usage-metering": {
"url": "https://gap-functions.bfurrow26.workers.dev/mcp"
}
}
}Remote endpoints
https://gap-functions.bfurrow26.workers.dev/mcpstreamable-httpWhat it can do
Tool inventory
Tools (5)
🟢mcp_usage_metering(caller_id, end_customer_ref, idempotency_key, metadata, source, ...)
Usage metering for MCP tools and AI agents: record a billable usage event per tool call (idempotent, idempotency_key dedupes retries) and get an invoice line preview. Per-call billing, usage-based pricing, metered billing for MCP servers. Every call requires one solved task: a tiny data packet, OR (this tool only) a public item: one line of public-domain text plus a deterministic format conversion (snake_case, word count, uppercase) with a known answer, returned as item_alternative; answer it within 2 s via item:{item_id, answer}. Verified answers are stored and readable at GET /items. Free first call, no API key (GET /try). Pay-ahead: every response carries next_work_packet; pass work_answer {work_packet_id, labels} on your next call (under 2 s) instead of solving a fresh packet. That work is our own internal classification (Buyer Zero), not customer data.
Input Schema
{
"type": "object",
"properties": {
"caller_id": {
"default": "demo_caller",
"title": "Caller Id",
"type": "string"
},
"end_customer_ref": {
"maxLength": 128,
"minLength": 1,
"title": "End Customer Ref",
"type": "string"
},
"idempotency_key": {
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Idempotency Key",
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"maxProperties": 20,
"title": "Metadata",
"type": "object"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
},
"tool_name": {
"maxLength": 128,
"minLength": 1,
"pattern": "^[A-Za-z0-9._/-]+$",
"title": "Tool Name",
"type": "string"
},
"tool_version": {
"pattern": "^\\d+\\.\\d+\\.\\d+$",
"title": "Tool Version",
"type": "string"
},
"unit_label": {
"default": "call",
"maxLength": 32,
"minLength": 1,
"title": "Unit Label",
"type": "string"
},
"unit_price_cents": {
"default": 0,
"maximum": 100000,
"minimum": 0,
"title": "Unit Price Cents",
"type": "integer"
},
"units": {
"default": 1,
"maximum": 1000000,
"minimum": 1,
"title": "Units",
"type": "integer"
}
},
"required": [
"tool_name",
"tool_version",
"end_customer_ref",
"idempotency_key"
],
"additionalProperties": false,
"title": "MeteringInput"
}🟡agent_spend_ledger(action, amount_micros, budget_id, caller_id, idempotency_key, ...)
Agent spend cap / budget ledger: set a budget, reserve before pay (atomic, never overspends even with many agents in parallel), then settle or release. Idempotent, shared by namespace. Spending limit, budget guard, cost control for AI agents. Every call requires a tiny solved packet (returned in the reply, 2 s, one try); free first call, no API key (GET /try?tool=agent_spend_ledger).
Input Schema
{
"type": "object",
"properties": {
"action": {
"enum": [
"set_budget",
"reserve",
"settle",
"release",
"status"
],
"title": "Action",
"type": "string"
},
"amount_micros": {
"default": 0,
"maximum": 1000000000000,
"minimum": 0,
"title": "Amount Micros",
"type": "integer"
},
"budget_id": {
"maxLength": 128,
"minLength": 1,
"pattern": "^[A-Za-z0-9._:/-]+$",
"title": "Budget Id",
"type": "string"
},
"caller_id": {
"default": "demo_caller",
"title": "Caller Id",
"type": "string"
},
"idempotency_key": {
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Idempotency Key",
"type": "string"
},
"limit_micros": {
"default": 0,
"maximum": 1000000000000,
"minimum": 0,
"title": "Limit Micros",
"type": "integer"
},
"memo": {
"default": "",
"maxLength": 200,
"title": "Memo",
"type": "string"
},
"namespace": {
"maxLength": 128,
"minLength": 16,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Namespace",
"type": "string"
},
"reservation_id": {
"anyOf": [
{
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Reservation Id"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
},
"ttl_s": {
"default": 900,
"maximum": 86400,
"minimum": 5,
"title": "Ttl S",
"type": "integer"
}
},
"required": [
"namespace",
"action",
"budget_id",
"idempotency_key"
],
"additionalProperties": false,
"title": "SpendLedgerInput"
}⚪agent_lease_lock(action, caller_id, holder_id, idempotency_key, lock_name, ...)
Distributed lock / lease lock (mutex) for AI agents: acquire, renew, release a named lock with TTL and a monotonic fencing token so only one agent runs a job at a time. Idempotent, shared by namespace, no Redis needed. Every call requires a tiny solved packet (returned in the reply, 2 s, one try); free first call, no API key (GET /try?tool=agent_lease_lock).
Input Schema
{
"type": "object",
"properties": {
"action": {
"enum": [
"acquire",
"renew",
"release",
"status"
],
"title": "Action",
"type": "string"
},
"caller_id": {
"default": "demo_caller",
"title": "Caller Id",
"type": "string"
},
"holder_id": {
"default": "",
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:/-]*$",
"title": "Holder Id",
"type": "string"
},
"idempotency_key": {
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Idempotency Key",
"type": "string"
},
"lock_name": {
"maxLength": 128,
"minLength": 1,
"pattern": "^[A-Za-z0-9._:/-]+$",
"title": "Lock Name",
"type": "string"
},
"namespace": {
"maxLength": 128,
"minLength": 16,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Namespace",
"type": "string"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
},
"ttl_s": {
"default": 60,
"maximum": 3600,
"minimum": 1,
"title": "Ttl S",
"type": "integer"
}
},
"required": [
"namespace",
"action",
"lock_name",
"idempotency_key"
],
"additionalProperties": false,
"title": "LeaseLockInput"
}⚪agent_semaphore(action, caller_id, holder_id, idempotency_key, max_slots, ...)
Counting semaphore / concurrency limit for AI agents: at most N agents hold a slot at once (rate limit parallel workers), TTL permits with fencing tokens, auto-expire on crash. Idempotent, shared by namespace. Every call requires a tiny solved packet (returned in the reply, 2 s, one try); free first call, no API key (GET /try?tool=agent_semaphore).
Input Schema
{
"type": "object",
"properties": {
"action": {
"enum": [
"acquire",
"release",
"status"
],
"title": "Action",
"type": "string"
},
"caller_id": {
"default": "demo_caller",
"title": "Caller Id",
"type": "string"
},
"holder_id": {
"default": "",
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:/-]*$",
"title": "Holder Id",
"type": "string"
},
"idempotency_key": {
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Idempotency Key",
"type": "string"
},
"max_slots": {
"default": 1,
"maximum": 1000,
"minimum": 1,
"title": "Max Slots",
"type": "integer"
},
"namespace": {
"maxLength": 128,
"minLength": 16,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Namespace",
"type": "string"
},
"permit_id": {
"default": "",
"maxLength": 64,
"pattern": "^[A-Za-z0-9_]*$",
"title": "Permit Id",
"type": "string"
},
"semaphore": {
"maxLength": 128,
"minLength": 1,
"pattern": "^[A-Za-z0-9._:/-]+$",
"title": "Semaphore",
"type": "string"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
},
"ttl_s": {
"default": 60,
"maximum": 3600,
"minimum": 1,
"title": "Ttl S",
"type": "integer"
}
},
"required": [
"namespace",
"semaphore",
"action",
"idempotency_key"
],
"additionalProperties": false,
"title": "SemIn"
}🟢agent_heartbeat_registry(action, agent_id, caller_id, grace_s, idempotency_key, ...)
Heartbeat registry / dead-man switch / liveness check for AI agents: agents beat with an interval and grace; list_stale shows which agents went silent or crashed. Idempotent, shared by namespace. Every call requires a tiny solved packet (returned in the reply, 2 s, one try); free first call, no API key (GET /try?tool=agent_heartbeat_registry).
Input Schema
{
"type": "object",
"properties": {
"action": {
"enum": [
"beat",
"status",
"list_stale"
],
"title": "Action",
"type": "string"
},
"agent_id": {
"default": "",
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:/-]*$",
"title": "Agent Id",
"type": "string"
},
"caller_id": {
"default": "demo_caller",
"title": "Caller Id",
"type": "string"
},
"grace_s": {
"default": 30,
"maximum": 86400,
"minimum": 0,
"title": "Grace S",
"type": "integer"
},
"idempotency_key": {
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Idempotency Key",
"type": "string"
},
"interval_s": {
"default": 60,
"maximum": 86400,
"minimum": 5,
"title": "Interval S",
"type": "integer"
},
"namespace": {
"maxLength": 128,
"minLength": 16,
"pattern": "^[A-Za-z0-9._:-]+$",
"title": "Namespace",
"type": "string"
},
"note": {
"default": "",
"maxLength": 200,
"title": "Note",
"type": "string"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
}
},
"required": [
"namespace",
"action",
"idempotency_key"
],
"additionalProperties": false,
"title": "HbIn"
}Community
Evidence