# ForgingStack Ration

> ForgingStack Ration is a freemium MCP server for developer tools. Shared quota pool for many agents with per-agent caps and receipts. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** API
- **Repository:** https://github.com/jdkabattles/forgingstack-ration
- **MCP Registry name:** io.github.jdkabattles/forgingstack-ration
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm)
- **Listing updated:** 2026-11-15

## About

Ration is a small hosted service with a thin client. The MCP server in the repository is only a stdio wrapper in Python's standard library; the token bucket, receipt chain, key store and billing run on ForgingStack's private service, so you need an API key and credits to use it.

A pool is created with a capacity, a refill rate, a per-agent cap and a burst limit. Agents draw units from it, and every draw attempt, allowed or denied, produces a hash-chained receipt. A draw is denied when it exceeds the burst limit, when the pool lacks units, or when the agent's draws inside a rolling 60-minute window would pass its cap. Replaying the same Idempotency-Key returns the original receipt at no charge.

Signup is a POST to the API and returns a key once, with 100 starter credits. Pool creation and each draw cost one credit, including denied draws, and a $10 pack buys 1,000 credits.

## Features

- **Pool limits:** Each pool has a capacity, refill rate, per-agent cap and burst limit.
- **Hash-chained receipts:** Allowed and denied draws both produce a receipt.
- **Rolling agent cap:** Per-agent limits use a rolling 60-minute window, not a calendar one.
- **Idempotent draws:** A repeated Idempotency-Key returns the original receipt for free.
- **Credit billing:** One credit per pool creation or draw; top-ups and reads are free.
- **Denial reasons:** Denials return codes such as draw_exceeds_burst and per_agent_cap_exceeded.

## Good for

- Cap how much of an API quota a team of agents can use
- Stop one runaway agent from draining a shared budget
- Keep an audit trail of every allowed and denied draw
- Refill a pool at a steady rate across scheduled agents

## Install

### Claude Code (Terminal)

```sh
claude mcp add forgingstack-ration --env FORGINGSTACK_API_KEY='<FORGINGSTACK_API_KEY>' -- uvx forgingstack-ration
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "forgingstack-ration": {
      "command": "uvx",
      "args": [
        "forgingstack-ration"
      ],
      "env": {
        "FORGINGSTACK_API_KEY": "<FORGINGSTACK_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "forgingstack-ration": {
      "command": "uvx",
      "args": [
        "forgingstack-ration"
      ],
      "env": {
        "FORGINGSTACK_API_KEY": "<FORGINGSTACK_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "forgingstack-ration": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "forgingstack-ration"
      ],
      "env": {
        "FORGINGSTACK_API_KEY": "<FORGINGSTACK_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "forgingstack-ration": {
      "command": "uvx",
      "args": [
        "forgingstack-ration"
      ],
      "env": {
        "FORGINGSTACK_API_KEY": "<FORGINGSTACK_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "forgingstack-ration": {
      "command": "uvx",
      "args": [
        "forgingstack-ration"
      ],
      "env": {
        "FORGINGSTACK_API_KEY": "<FORGINGSTACK_API_KEY>"
      }
    }
  }
}
```

## Tools

- `create_pool`: Creates a quota pool
- `draw`: Draws units from a pool
- `get_pool`: Reads a pool
- `list_pools`: Lists pools
- `topup_pool`: Adds units to a pool
- `delete_pool`: Deletes a pool
- `get_credits`: Shows remaining credits
- `get_receipt`: Fetches a receipt

## FAQ

### Is the service open source?

Only the client is. The service itself runs privately and is not in the repository.

### How much does it cost?

New keys get 100 starter credits. A $10 pack buys 1,000 credits; pool creation and each draw cost one credit.

### Does a denied draw cost anything?

Yes, one credit, because the draw was performed. An idempotent replay is free.

### Do I need to verify my email?

Yes. Until the verification link is clicked, creating pools and drawing return 403 email_not_verified.

### Is ForgingStack Ration free?

ForgingStack Ration has a free plan, with paid plans for more usage or features.

### How do I add ForgingStack Ration to Claude Code?

Run this command in your terminal: claude mcp add forgingstack-ration --env FORGINGSTACK_API_KEY='<FORGINGSTACK_API_KEY>' -- uvx forgingstack-ration

### What are the best alternatives to ForgingStack Ration?

The closest alternatives to ForgingStack Ration are ForgingStack Mandate Check, Agentics, AgentPay — trust routing + spend caps for x402 agents, AgentLedger and SmartGate.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [ForgingStack Mandate Check](https://ai-powered.com/mcp/forgingstack-mandate-check): ForgingStack Mandate Check is a paid MCP server for security.
- [Agentics](https://ai-powered.com/mcp/agentics): Agentics is a freemium MCP server for knowledge and memory.
- [AgentPay — trust routing + spend caps for x402 agents](https://ai-powered.com/mcp/agentpay-trust-routing-spend-caps-for-x402-agents): AgentPay — trust routing + spend caps for x402 agents is a freemium MCP server for finance and payments.
- [AgentLedger](https://ai-powered.com/mcp/agentledger): AgentLedger is a freemium MCP server for finance and payments.
- [SmartGate](https://ai-powered.com/mcp/smartgate): SmartGate is a freemium MCP server for developer tools.
- [Fatstack](https://ai-powered.com/mcp/fatstack): Fatstack is a paid MCP server for finance and payments.
- [Codex4ever](https://ai-powered.com/mcp/codex4ever): Codex4ever is an open-source MCP server for developer tools.
- [Good-neighbor passport: agent traffic governor](https://ai-powered.com/mcp/good-neighbor-passport-agent-traffic-governor): Good-neighbor passport: agent traffic governor is an MCP server for security.

---
Source: https://ai-powered.com/mcp/forgingstack-ration
