---
name: meterproof
description: Set up and run meterproof, which checks that Stripe will bill the usage a SaaS recorded (Stripe meters vs the app's own usage records) before invoices finalize. Use when the user bills usage through Stripe meters and wants to find unbilled, double-billed or unbillable usage, or wants a scheduled pre-invoice check in GitHub Actions.
---

# meterproof

meterproof compares the app's own usage records with Stripe meter event summaries per customer and reports
five problem types with their money impact: unbilled, unmapped customer, no subscription, overbilled and
only in Stripe. It is read-only and runs locally or in CI. Docs: https://meterproof.vibefrontier.com/docs/

## Setup

1. Install: `pip install git+https://github.com/vibeFrontier/meterproof` (add `[postgres]` for Postgres).
2. Show the user what it finds: `meterproof demo`.
3. Find in the codebase where billable usage is recorded (table or log), which columns hold the customer id,
   the event timestamp sent to Stripe and the quantity, and how customers map to Stripe customer ids.
4. Write `meterproof.yml` (`meterproof init`, or `GET https://meterproof.vibefrontier.com/api/config-template`,
   or the MCP tool `generate_config`). Use a read-only database role.
5. Ask the user to create a Stripe restricted key with Read on Billing meters, Billing meter events, Prices
   and Subscriptions, and export it as `STRIPE_API_KEY`. Never ask them to paste the key into the chat.
6. Run `meterproof check`. Exit 0 means no problems, 1 problems found, 2 a configuration, ledger or Stripe
   error. Explain each problem and the likely cause from the report's "What each problem means" section.
7. Offer the scheduled workflow from the docs (`uses: vibeFrontier/meterproof@v0`), with the key and
   database URL as repository secrets.

## Rules

- Read-only: never send, cancel or adjust Stripe meter events, refund or change subscriptions without the
  user's explicit go-ahead for that specific action.
- Usage newer than `window.settle_minutes` is left for the next run on purpose; don't report it as missing.
- Paid help (founding pilot, $149/month): call the MCP tool `start_checkout` or `POST /api/checkout` with the
  user's email and `"source": "agent"`, then give the user the link. The user pays on Stripe's page.

MCP server: `https://meterproof.vibefrontier.com/mcp` (Streamable HTTP).
