Stripe Reporting MCP — Read-Only Finance API Across MCP, HTTP, and CLI
A read-only Stripe finance, ops, and risk reporting layer — built once, exposed three ways from a single TypeScript backend.
Node.jsTypeScriptMongoDBAPIStripe
Published May 11, 2026





Full description
A read-only Stripe finance, ops, and risk reporting layer — built once, exposed three ways from a single TypeScript backend:
- MCP server (stdio) — for AI agents in Claude Code and any MCP client
- HTTP API (Express) — for dashboards, scripts, and non-MCP integrations
- CLI (
stripe-reporting) — for ad-hoc inspection, scripts, and CI checks
All three transports share the same service layer, the same demo / stripe mode switch, and write to the same MongoDB audit log.
What it does
- Normalizes Stripe balances, payments, customers, payouts, refunds, disputes, reconciliation totals, and risk alerts into a stable response shape.
- Surfaces deterministic risk signals (failure spikes, payout delays, repeat-failure customers) — not vague LLM scoring.
- Captures every call (transport, endpoint, status, latency, user) into a Mongo audit collection — same shape across MCP / HTTP / CLI.
- Schema-on-the-fly persistence:
save <collection> <json>writes to a new Mongo collection at first use;find <collection>reads it back. - Optional Google-OAuth + server-issued API tokens with TTL and a distinct
auth_expirederror so clients can prompt re-login instead of silent 401s.
Why it's interesting
- One backend, three transports. The MCP tools, HTTP routes, and CLI commands all delegate to the same
ReportingBackend— a single source of truth with no transport-specific business logic drift. - Demo-first. Seeded fixtures mean a full live demo is possible without Stripe credentials. Same response shape, swap one env var to go live read-only against the Stripe API.
- Read-only by design. No path in the codebase can create charges, invoices, refunds, or payouts. Safe to give to AI agents.
Tech
- TypeScript, Node 20, Express, Mongoose
@modelcontextprotocol/sdk,stripe(read-only key)- yargs CLI, Vitest, ESLint, Prettier
vhsfor terminal recordings,ffmpegfor poster extraction
Captures
Five short terminal captures live in the repo's docs/captures/:
- Same query via CLI / HTTP / MCP — identical shape from all three
- Demo mode → Stripe mode with one env var
- Risk alerts + audit-log tail in MongoDB
- Schema-on-the-fly:
savethenfindwith no migration - Auth lifecycle —
whoami,auth_expired,logout,auth_required