Budget Governor

Budget & cost control for AI agents: hard per-agent spend caps, rate limits, idempotency, and human-in-the-loop approval — enforced before each LLM call, not…

CommunityOnlineAPI key requiredGlobalFreeRead-only

What it can do

  • Budget Clear: Pre-flight authorization for a planned LLM call. Estimates cost from model + estimated_tokens, deducts from the agent envelope, returns {approved:true, remaining_usd} or {approved:false,
  • Set Envelope: Create or update a per-agent USD spend envelope. Idempotent: re-calling preserves the running spent_usd and reset_at; only limit_usd and window are overwritten. `window:"daily"` resets a
  • Get Balance: Read-only snapshot of the account-level governance-operation quota. The quota is increased by pay-as-you-go USDC topups (any amount, credited at 1,000 ops per $1) and decreased by one per

What data it sees

Do you need an account

An API key from the service settings is required

Budget & cost control for AI agents: hard per-agent spend caps, rate limits, idempotency, and human-in-the-loop approval — enforced before each LLM call, not after the invoice. One hosted MCP endpoint, settled via x402 (USDC on Base).

How to connect

How to connect Budget Governor to Claude

The server address to paste into Claude settings:

https://gvnr--mightbesaad.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect Budget Governor to ChatGPT

The server address to paste into ChatGPT settings:

https://gvnr--mightbesaad.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect Budget Governor to Cursor

The server address to paste into Cursor settings:

https://gvnr--mightbesaad.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (10)

Raw names from tools/list. Only developers need these.

budget_clearPre-flight authorization for a planned LLM call. Estimates cost from model + estimated_tokens, deducts from the agent envelope, returns {approved:true, remaining_usd} or {approved:false, reason}. Call BEFORE the LLM request; if approved=false, skip the call. Pair with `reconcile` AFTER the LLM responds to correct drift between estimate and actual. For chat models pass output tokens; for embedding models (text-embedding-3-*, gemini-embedding-*) pass input tokens since those are billed input-only.
set_envelopeCreate or update a per-agent USD spend envelope. Idempotent: re-calling preserves the running spent_usd and reset_at; only limit_usd and window are overwritten. `window:"daily"` resets at UTC midnight; `window:"session"` never resets (caller-managed). Must be set before `budget_clear` will approve calls for this agent — clearance against an unset envelope returns approved:false. Spend is updated by `budget_clear` (estimated) and `reconcile` (corrected).
get_balanceRead-only snapshot of the account-level governance-operation quota. The quota is increased by pay-as-you-go USDC topups (any amount, credited at 1,000 ops per $1) and decreased by one per `budget_clear`. Your LLM token spend is billed by your provider, not here; per-agent spend caps are separate — see `set_envelope`. Returns {operations_remaining:number}.
reconcilePost-call drift correction. After the LLM returns, call this with the actual input/output token counts from the provider response — applies the delta (actual minus estimated cost) to the agent envelope (the spend cap); the operation quota is unchanged. Pairs with `budget_clear`: clear runs the estimate, reconcile runs the correction. If reconcile is skipped, the estimated cost stands. Not idempotent — calling twice double-corrects; gate with `idempotency_check` if your retry policy requires it.
set_rate_envelopeCreate or update a rate-limit envelope scoped to the (agent_id, provider, model) triple. Each triple gets its own independent counter — different agents on the same model do not share quota. Fixed 60-second window (not sliding). Idempotent: re-calling updates requests_per_minute without resetting the current window counter. Must be set before `rate_check` can return allowed:true for this triple — checks against an unset envelope return allowed:false.
rate_checkCheck the rate-limit envelope for an (agent_id, provider, model) triple before making an LLM call. Returns {allowed:true, requests_remaining_this_minute} if under cap (and increments the counter), or {allowed:false, reason:"rate_exceeded", retry_after_ms} if over. Pairs with `set_rate_envelope` (which must be called first) and typically follows `budget_clear` in the request prologue: clear → rate_check → LLM call → reconcile. Not idempotent — each call counts as one request.
idempotency_checkDedupe retries on a caller-supplied key. Returns {is_first_call:true} the first time a key is seen within TTL; returns {is_first_call:false} on every subsequent call. Use as a guard around non-idempotent operations — common pairings: gate `reconcile` to prevent double-correction, gate `request_approval` to prevent duplicate human notifications, gate side-effectful tool calls (emails, payments, writes) to survive agent retry loops. Keys are account-scoped; choose keys that uniquely identify the logical operation, not the attempt.
request_approvalRequest human approval for an agent action. Returns immediately with {approval_id, approval_url, expires_at}; the human approves or denies via the URL (mobile-first web page), and the agent polls `check_approval` with approval_id to learn the decision. Notifies the account holder via the configured channel (V1: email only; telegram/sms accepted in schema but rejected with channel_not_implemented; email delivery may be silently skipped when no provider is configured server-side). NOT idempotent — each call creates a new pending approval and a new notification; gate with `idempotency_check` if your retry policy could fire twice for the same logical action.
check_approvalPoll the status of a pending approval created by `request_approval`. Returns {decision: "pending"} while the human has not decided, {decision: "approved"} or {decision: "denied"} once they have, or {decision: "timeout"} if expires_at passed without a decision. Read-only and idempotent — safe to call repeatedly. Suggested poll interval: ≥5s. The human-facing approval page is at the approval_url returned by request_approval.
view_dashboardOpen an interactive, read-only spend dashboard for this account: an operation-quota gauge plus a live bar per agent showing spent vs. envelope limit, remaining USD, and daily-reset countdown, with a recent-clearance activity feed. Use when a human asks how their budget or an agent's spend is doing. The panel auto-refreshes while open. Takes no arguments — it reports on the account tied to your API key.