Skip to main content
Glama

ForgingStack Ration

One quota pool, many agents, no overruns.

mcp-name: io.github.jdkabattles/forgingstack-ration

This is the public client for Ration. The service itself — the token bucket, the receipt chain, the key store, and billing — runs on ForgingStack's private service and is not in this repo. Copying this repo does not give you the service: you still need an API key and credits, from signup below.

Live API: https://forgingstack-ration.jkbattles.workers.dev

What it does

A principal creates a pool with a capacity, a refill rate, a per-agent cap, and a burst limit. Agents draw units from it. The pool enforces the limits and issues a hash-chained receipt for every draw attempt — allowed and denied.

A draw is denied when:

  • the units exceed the burst limit (draw_exceeds_burst)

  • the pool does not have enough available units (pool_insufficient_units)

  • the agent's allowed draws inside the rolling 60-minute window would exceed the per-agent cap (per_agent_cap_exceeded)

The per-agent cap window is a rolling 60 minutes — a documented design choice, not a calendar window.

Related MCP server: genpark-api-rate-limit-token-bucket-throttle-skill

Signup (v1)

curl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Returns an API key once and 100 starter credits. Save the key immediately — it is stored only as a hash and cannot be shown again. Click the verification link in the signup email before the key can create pools or draw: until then, pool creation and draws return 403 email_not_verified.

Buying more credits

1 credit per pool creation, 1 credit per draw call (allowed or denied). Top-ups, pool reads, pool lists, and deletes are free.

curl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/billing/checkout \
  -H "X-API-Key: YOUR_PRIMARY_KEY"

Returns the Stripe Payment Link: $10 for 1,000 credits. Pay on Stripe's hosted page with the same email you signed up with. Credits land once the payment is verified (within the hour).

Use it (MCP, stdio)

Set the key, then run the MCP server in this repo:

export FORGINGSTACK_API_KEY="your-key-here"
python -m app.mcp_server

Tools: create_pool, draw, get_pool, list_pools, topup_pool, delete_pool, get_credits, get_receipt. See SKILL.md for when to use it and when not to.

Price

1 credit per pool creation. 1 credit per draw call — a denied draw still costs 1 credit, the draw was performed. An idempotent replay (same Idempotency-Key) is free and returns the original receipt.

Files in this repo

  • app/mcp_server.py — MCP wrapper client (stdio, stdlib only)

  • SKILL.md — when to use it, how to read allowed/denied

  • agent-card.json — A2A-style discovery card

  • server.json — MCP Registry metadata

  • pyproject.toml — package metadata for the MCP client

Available Tools

8 tools
create_poolC

Create a token-bucket quota pool shared by many agents. Costs 1 credit. Returns the pool with its starting availability.

Inputs: name (required), burst_units (required), capacity_units (required), per_agent_cap_units (required), +1 more.

delete_poolA

Delete a pool and its draws. No billing credit is charged or refunded.

Inputs: pool_id (required).

drawA

Draw units from a pool for one agent. Returns allowed or denied, a reason, and a hash-chained receipt. Costs 1 credit per draw call, allowed or denied; an idempotency key replay is free.

Inputs: units (required), pool_id (required), agent_id (required), idempotency_key.

get_creditsB

Remaining credit balance for the configured API key.

Inputs: no named parameters.

get_poolB

Fetch one pool by id, with its current available units (refill applied).

Inputs: pool_id (required).

get_receiptC

Fetch a past draw receipt by id.

Inputs: receipt_id (required).

list_poolsA

List all pools owned by the configured API key.

Inputs: no named parameters.

topup_poolC

Add units to a pool, clamped at capacity. Free — no billing credit is charged.

Inputs: units (required), pool_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource-action pair: pool lifecycle (create/get/list/topup/delete), unit consumption (draw), receipts (get_receipt), and billing (get_credits). The only near-pair, create_pool vs topup_pool, is cleanly separated by creation-vs-augmentation and by cost semantics. No two tools appear interchangeable.

    Naming Consistency4/5

    Seven of eight tools follow a consistent snake_case verb_noun pattern (create_pool, get_pool, list_pools, topup_pool, delete_pool, get_credits, get_receipt). The lone bare verb 'draw' breaks the pattern, though its meaning remains obvious.

    Tool Count5/5

    Eight tools is well within the sweet spot and every tool earns its place: CRUD on pools, the core draw operation, and supporting receipt/credit lookups. No redundancy or filler.

    Completeness4/5

    Pool lifecycle is well covered (create, read, list, topup, delete) plus draw and receipt retrieval, with billing visibility via get_credits. Gaps remain: no way to enumerate draws/receipts for a pool (receipts only fetchable by known id) and no way to adjust pool capacity or refill rate after creation.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers