Gvnr MCP server

Gvnr

Spend caps, rate coordination, idempotency, and a human-in-the-loop gate for AI agents — enforced before the call, not after the invoice. One MCP endpoint, settled via x402 (USDC on Base). No proxy, no self-hosting, no infrastructure to deploy.

Listed on the Official MCP Registry as dev.gvnr/gvnr.

The problem

Agents cost 10–12× more than estimated in production. System prompts, retry loops, and tool calls multiply fast — a runaway agent can generate a $47,000 bill in 11 days. The usual fix, self-hosting a gateway like LiteLLM, means running infrastructure most developers won't set up.

Gvnr is the hosted alternative: an external authority your agent checks before it spends. Your agent asks "am I clear to make this call?" and acts on the answer.

How it works

Gvnr is not an LLM proxy — your tokens never pass through it, and you pay your model provider directly. Gvnr governs the decision to spend, in two independent meters:

1. The governance-operation quota — what you buy from Gvnr. Your account holds a balance of governance operations (operationsremaining). One budgetclear burns one op. You top this up with USDC; it's decoupled from your LLM spend. get_balance reports it.

2. The spend envelope — a USD cap you set, per agent. setenvelope(agentid, limit_usd, window) gives an agent a daily or per-session USD ceiling. Gvnr tracks estimated spend against it and denies once it's exceeded — this is the runaway guardrail. No dollars move; it's an accounting limit you control.

A budgetclear is approved only when both** hold: the account has ops left in the quota, and the agent is under its envelope. The loop:

1. Your agent calls budgetclear(agentid, model, estimated_tokens) before each LLM request.
2. Gvnr checks the op quota and the agent's envelope, and returns { approved: true, ... } or { approved: false, reason }.
3. If denied, your agent skips (or escalates via request_approval).
4. After the LLM responds, call reconcile(...) with the real token counts so the envelope tracks actual cost, not the estimate.

Quick start

1. Provision an account

curl -X POST https://gvnr.dev/v1/account
# { "api_key": "bg_...", "account_id": "...", "operations_remaining": 25 }

New accounts include 25 free trial ops — enough to run the full loop (set an envelope, budgetclear, reconcile) before you fund anything. Your apikey is the credential for every call; accountid is just an internal reference for support. Account creation is credential-only by design (agent-native) — email is optional**, set separately via POST /v1/account/notification-email, and used only for human approval notices.

2. Top up your governance-op quota

Pay-as-you-go: 1,000 ops per $1, any amount (try the whole rail for $1), USDC on Base. Open the pay page, name your amount, and pass your API key:

https://gvnr.dev/pay?usd=1&api_key=bg_YOUR_KEY

Shortened. The full README is on GitHub.