{"id":"d737ff6a-6a37-4a0d-88f8-09bd0b29b4f8","slug":"forgingstack-ration","kind":"mcp","name":"forgingstack-ration","summary":"ForgingStack Ration — one quota pool, many agents, no overruns. Public MCP client for the live Ration API.","owner":"jdkabattles","repoUrl":"https://github.com/jdkabattles/forgingstack-ration","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-11-08T17:36:30.000Z","addedAt":"2026-11-08T23:26:34.709Z","logoUrl":"https://avatars.githubusercontent.com/u/241386083?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":true,"reviewed":false,"syncedAt":"2026-11-08T23:28:54.229Z","sample":false,"url":"https://conduits.dev/tools/forgingstack-ration","language":"Python","transports":["stdio"],"install":{"pypi":"forgingstack-ration"},"requirements":{"env":[{"name":"FORGINGSTACK_API_BASE","secret":false,"required":false,"description":"Ration API base URL. Live default."},{"name":"FORGINGSTACK_API_KEY","secret":true,"required":true,"description":"API key for Ration. Sign up via POST /v1/signup (key shown once)."}],"upstreamMayCharge":false},"tools":null,"readme":"# ForgingStack Ration\n\nOne quota pool, many agents, no overruns.\n\nmcp-name: io.github.jdkabattles/forgingstack-ration\n\nThis is the **public client** for Ration. The service itself — the\ntoken bucket, the receipt chain, the key store, and billing — runs\non ForgingStack's private service and is **not** in this repo.\nCopying this repo does not give you the service: you still need an\nAPI key and credits, from signup below.\n\nLive API: https://forgingstack-ration.jkbattles.workers.dev\n\n## What it does\n\nA principal creates a pool with a capacity, a refill rate, a\nper-agent cap, and a burst limit. Agents draw units from it. The\npool enforces the limits and issues a hash-chained receipt for\nevery draw attempt — allowed **and** denied.\n\nA draw is denied when:\n\n- the units exceed the burst limit (`draw_exceeds_burst`)\n- the pool does not have enough available units\n  (`pool_insufficient_units`)\n- the agent's allowed draws inside the rolling 60-minute window\n  would exceed the per-agent cap (`per_agent_cap_exceeded`)\n\nThe per-agent cap window is a rolling 60 minutes — a documented\ndesign choice, not a calendar window.\n\n## Signup (v1)\n\n```bash\ncurl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"you@example.com\"}'\n```\n\nReturns an API key **once** and 100 starter credits. Save the key\nimmediately — it is stored only as a hash and cannot be shown again.\nClick the verification link in the signup email before the key can\ncreate pools or draw: until then, pool creation and draws return\n403 `email_not_verified`.\n\n## Buying more credits\n\n1 credit per pool creation, 1 credit per draw call (allowed or\ndenied). Top-ups, pool reads, pool lists, and deletes are free.\n\n```bash\ncurl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/billing/checkout \\\n  -H \"X-API-Key: YOUR_PRIMARY_KEY\"\n```\n\nReturns the Stripe Payment Link: **$10 for 1,000 credits**. Pay on\nStripe's hosted page with the same email you signed up with.\nCredits land once the payment is verified (within the hour).\n\n## Use it (MCP, stdio)\n\nSet the key, then run the MCP server in this repo:\n\n```bash\nexport FORGINGSTACK_API_KEY=\"your-key-here\"\npython -m app.mcp_server\n```\n\nTools: `create_pool`, `draw`, `get_pool`, `list_pools`,\n`topup_pool`, `delete_pool`, `get_credits`, `get_receipt`.\nSee `SKILL.md` for when to use it and when not to.\n\n## Price\n\n1 credit per pool creation. 1 credit per draw call — a denied draw\nstill costs 1 credit, the draw was performed. An idempotent replay\n(same `Idempotency-Key`) is free and returns the original receipt.\n\n## Files in this repo\n\n- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)\n- `SKILL.md` — when to use it, how to read allowed/denied\n- `agent-card.json` — A2A-style discovery card\n- `server.json` — MCP Registry metadata\n- `pyproject.toml` — package metadata for the MCP client\n"}