Budget Governor
About
Hard spend cap for autonomous AI agents. One MCP call before each LLM request — approved or denied before the call reaches any provider. No deployment. No proxy. No self-hosting.
Details
- Transport
- SSE
Explore
- Hard spend cap for autonomous AI agents.
- One MCP call per LLM request for approval/denial.
- No deployment, proxy, or self-hosting required.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Budget GovernorCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
—
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, 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_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 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_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 `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}.
reconcile
Post-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_envelope
Create 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_check
Check 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_check
Dedupe 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 th…
request_approval
Request 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 idempoten…
check_approval
Poll 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_dashboard
Open 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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"budget governor": {
"budget-governor": {
"type": "http",
"url": "https://gvnr.dev/mcp?api_key=<YOUR_API_KEY>"
}
}
}
}McpServers
{
"budget-governor": {
"type": "http",
"url": "https://gvnr.dev/mcp?api_key=<YOUR_API_KEY>"
}
}Hard spend cap for autonomous AI agents. One MCP call before each LLM request — approved or denied before the call reaches any provider. No deployment. No proxy. No self-hosting.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
