MCP-Billing

Product Introduction

1. Definition: MCP-Billing is a self-hosted, production-ready boilerplate built with Next.js 15 and TypeScript. It is a technical infrastructure layer designed specifically for developers building monetizable Model Context Protocol (MCP) servers. It provides a complete, integrated backend for authentication, API management, and usage-based billing.
2. Core Value Proposition: It exists to eliminate the weeks of development time typically required to implement secure, compliant, and reliable monetization infrastructure for MCP servers. Its primary value is enabling developers to ship an MCP server with billing and OAuth on day one, transforming a complex, multi-week integration project into a deployable solution in hours.

Main Features

1. OAuth 2.1 with PKCE Implementation: Provides a pre-built, standards-compliant OAuth 2.1 authorization server with Proof Key for Code Exchange (PKCE). It handles the entire flow—client registration, token issuance, and refresh—without requiring developers to manually implement RFC specifications. This ensures secure authentication for MCP server clients right out of the box.
2. Idempotent API Key Management with Zero-Downtime Rotation: Features a dashboard and programmatic endpoints for generating, rotating, and revoking API keys. The system supports zero-downtime key rotation, allowing new keys to be issued before old ones are revoked, preventing service interruption for end-users. All key states and permissions are managed within the system.
3. Stripe-Powered Usage-Based Metering with Edge-Case Handling: Integrates directly with Stripe Billing to meter usage (e.g., per API call, per token) and generate invoices. Its core innovation is explicit handling of real-world edge cases: it uses idempotencyKey to prevent double-charging on retries, classifies interrupted streams as partial (excluded from billing by default), and ensures billing events are committed only upon successful operation completion.
4. Redis-Backed Rate & Quota Limiting: Implements configurable rate limiting using Redis for fast, distributed state management. This protects the MCP server backend from abuse and enforces usage quotas per user or API key, using a sliding-window algorithm that developers do not need to build from scratch.
5. Multi-Tenant Ready Architecture: The system is built from the ground up to support multiple independent clients. Each OAuth client or API key holder operates within an isolated context with separate billing accounts, usage quotas, and rate limits, making it suitable for SaaS-style MCP server offerings.
6. Decoupled, Framework-Agnostic Design: The billing and auth layer runs independently of the core MCP server logic. Communication happens via internal API calls, meaning the MCP server itself can be built in any language or framework (Node.js, Python, etc.). This prevents infrastructure lock-in and allows the product logic to evolve separately.

Problems Solved

1. Pain Point: The immense time sink and complexity of manually implementing production-grade OAuth 2.1, secure API key lifecycle management, and reliable usage-based billing. Developers often spend weeks reading RFCs and handling billing edge cases instead of building their core MCP server functionality.
2. Target Audience: Indie MCP Server Developers and Small Dev Teams looking to monetize their MCP tools; SaaS Companies integrating MCP servers into their existing platform who need a secure, billable API layer; Enterprise Developers requiring a self-hosted, auditable billing and auth solution to avoid third-party platform lock-in.
3. Use Cases: A developer creates a specialized MCP server for financial data analysis and needs to charge per query. A team builds an MCP server for internal company use but must track and limit department-level usage. An indie hacker wants to launch a paid MCP service quickly without managing recurring platform fees from third-party auth/billing services.

Unique Advantages

1. Differentiation: Unlike generic backend starters or Stripe/Okta SDKs, MCP-Billing is a vertically integrated solution specifically for the MCP server ecosystem. It differs from platform-as-a-service (PaaS) offerings by being self-hosted with a one-time fee, eliminating ongoing revenue share or subscription costs. It provides more complete, production-tested handling of billing idempotency and streaming than any available open-source alternative.
2. Key Innovation: The "decisioned" billing core, informed by feedback from production MCP servers. It bakes in critical, non-obvious decisions—like not billing for partial failures by default and committing usage in a single transaction—that are typically only learned through painful experience. This is validated by its 300+ unit and integration tests. The extraction of the mcp-metering pattern as a free, open-source npm package serves as verifiable proof of this technical quality.

Frequently Asked Questions (FAQ)

1. How does MCP-Billing handle retries and prevent double-charging in usage-based billing? Every usage event must include a unique idempotencyKey. The system checks this key against a Redis store. If the same key is processed again (due to a client retry or network issue), it returns the recorded result without creating a new billing event in Stripe, guaranteeing idempotent operation.
2. Is MCP-Billing compatible with MCP servers not written in TypeScript or Node.js? Yes. Its architecture is decoupled. While the boilerplate itself is a Next.js application, it exposes authentication and billing functionality via internal API endpoints. Your core MCP server logic, written in any language (Python, Go, etc.), can call these endpoints to validate API keys, check quotas, and record usage, making it framework-agnostic.
3. What happens if a user's API call or stream is interrupted mid-way? The system records the event with a status: 'partial'. By default, these partial events are logged for auditing but are not sent to Stripe for billing. The policy for charging partial usage is configurable, allowing developers to decide based on their business model (e.g., charge for partial compute).
4. Can I use this for client projects or within my company commercially? Yes. The commercial license included with the one-time purchase allows for unlimited use in both personal and commercial projects, including client work. The only restriction is that you cannot resell the MCP-Billing boilerplate code itself as a product.
5. How does the OAuth 2.1 implementation handle security concerns like PKCE? The implementation is built to the OAuth 2.1 specification, which mandates PKCE for all public clients. This prevents authorization code interception attacks. The boilerplate handles the generation and verification of the code verifier and challenge automatically, ensuring a secure flow without developer intervention.