CONCEPTS

TOPOLOGY

Three actors, one transit. Your agent (consumer) opens a long-lived MCP connection to proxy.mcpmeter.com/<slug>. We authenticate, meter, and forward each tool call to the publisher's upstream MCP. The response streams back unchanged. Every call writes one row to the ledger.

EXECUTION SEQUENCE

On every call the proxy executes a fixed seven-step pipeline. If any step fails, no debit happens and the response carries a precise status code (see errors).

1. Authenticate. The bearer key is hashed (SHA-256) and looked up in Redis. The cached row resolves to a project, monthly cap, and account state. Cache TTL: 60s.
2. Resolve MCP. The slug resolves to the publisher's upstream URL, transport, free tier, and rate limits. Cached.
3. Rate limit. Per-(MCP, consumer) per-minute and per-day counters in Redis. Over either ceiling → 429 with Retry-After.
4. Free tier. If within the publisher's monthly free allowance, mark FREE and skip the debit step. Free-tier counters reset on the 1st of each calendar month.
5. Credit gate. Atomic credit debit in PostgreSQL using SELECT ... FOR UPDATE + balance check. Insufficient balance → 402.
6. Forward. Stream JSON-RPC body to the publisher's MCP, pass the response back unmodified.
7. Record. One row per call to usage_events, async-batched. Includes status, duration, byte counts, and µ¢ debit.

METERING MODEL

Prices are stored in µ¢ (micro-cents). One US dollar is 1,000,000 µ¢. We use this precision because typical per-call prices ($0.0002) would round to zero in cents.

The credit balance, every pricing rule, every ledger row — all µ¢. Conversion happens in the view layer.

BALANCE & LEDGER

Every consumer has a single credit_micro_cents balance. Top-ups credit it; metered calls debit it. The ledger (credit_transactions) records every change with a balance_after_micro_cents snapshot so you can audit any moment in history.

Transaction types:

• signup_bonus — the $0.10 starter credit
• topup — Stripe Checkout settled
• usage — metered call debit (negative)
• refund — upstream 5xx, debit reversed
• adjustment — manual support adjustment
• promo — promo code credit

PROJECTS

Projects are spend buckets owned by a consumer. Each carries an optional monthly cap. The proxy returns 402 when month-to-date spend on a project exceeds its cap, even if the global account balance is fine. Useful for separating production from dev, or capping a noisy agent.

Every API key is bound to exactly one project. Spending caps live on the projects page.

PUBLISHER PAYOUTS

Publishers receive payouts on the 1st of each calendar month for the prior month's usage. Settlement is via Stripe Connect Express. The platform take rate is 10% for the first 100 publishers (founders' rate, locked for 12 months), then 20% standard.

For the math — settlement, fees, refunds — see pricing model.

PRIVACY MODEL

The proxy logs metadata only: slug, tool name, status, duration, byte counts. We do not persist JSON-RPC bodies. Audit logs retain for 13 months in your region.