# Agent Billing Primitives (Dirtsmith)

> Usage metering, spend cap (reserve before pay), lease lock, semaphore, heartbeat for agents. Free tr

- name: io.github.throttler300/mcp-usage-metering
- version: 1.4.0
- connection class: R0 (autonomous)
- trust: 94/100
- quality: 73/100 (new)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.throttler300%2Fmcp-usage-metering
- tools: https://api.protogrid.dev/v1/servers/io.github.throttler300%2Fmcp-usage-metering/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "mcp-usage-metering": {
      "type": "http",
      "url": "https://gap-functions.bfurrow26.workers.dev/mcp"
    }
  }
}
```


## Trust

- hygiene: 100
- liveness: 100
- freshness: 100
- provenance: 80
- drivers: +repository +namespace-matches-repo +reachable +uptime-100% +updated-3d-ago
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 73/100 (new)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-11-25; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 71 (weight 30)

- pass `tools.descriptions`: every tool has a description
- pass `tools.description_length`: descriptions are concise
- pass `tools.schemas`: every tool has an object input schema
- fail `tools.annotations`: no tool declares readOnlyHint or destructiveHint, so clients cannot tell safe calls from risky ones
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: mcp_usage_metering (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); agent_spend_ledger (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); agent_semaphore (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); …
- pass `tools.token_cost`: about 1,971 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: n/a (weight 15)

- n/a `stability.changes`, `stability.rug_pull`: tool history recorded for 3 of the 7 days needed

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 5, about 1,971 tokens to load them all
- tool set hash: 11b3c7e388905b1e31629431be16544a
- tools last changed: 2026-11-04T17:15:07.443Z
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.throttler300/mcp-usage-metering.svg)](https://protogrid.dev/servers/io.github.throttler300/mcp-usage-metering)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

- 2026-11-04 `agent_heartbeat_registry` added
  - 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).
- 2026-11-04 `agent_semaphore` added
  - 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).
- 2026-11-04 `agent_lease_lock` changed (description) **meaning changed**
  - before: Hosted distributed lease lock for agents: acquire/renew/release a named lock with a TTL and a monotonic fencing token so only one agent does a job at a time. Share state by namespace
  - after: 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).
- 2026-11-04 `agent_spend_ledger` changed (description) **meaning changed**
  - before: Hosted shared spend ledger for agents: set a budget ceiling, atomically reserve before paying (never overspends, even with many agents at once), then settle or release. Idempotent. Share state by namespace
  - after: 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).
- 2026-11-04 `mcp_usage_metering` changed (description) **meaning changed**
  - before: Record a metered usage event for any MCP tool call and return an invoice line preview (dry run)
  - after: 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.
- 2026-11-04 `agent_lease_lock` added
  - Hosted distributed lease lock for agents: acquire/renew/release a named lock with a TTL and a monotonic fencing token so only one agent does a job at a time. Share state by namespace
- 2026-11-04 `agent_spend_ledger` added
  - Hosted shared spend ledger for agents: set a budget ceiling, atomically reserve before paying (never overspends, even with many agents at once), then settle or release. Idempotent. Share state by namespace

Full history: https://api.protogrid.dev/v1/servers/io.github.throttler300%2Fmcp-usage-metering/changes

## Remotes

- https://gap-functions.bfurrow26.workers.dev/mcp (streamable-http, auth none, reachable true, uptime30d 1)

## Packages

_none_

## Tools (5)

- `agent_heartbeat_registry`: 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).
- `agent_lease_lock`: 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).
- `agent_semaphore`: 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).
- `agent_spend_ledger`: 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).
- `mcp_usage_metering`: 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.