mcp-boilerplate

Deploys a Model Context Protocol server on Cloudflare Workers, providing a globally distributed, edge-compute endpoint for AI assistants. The system uses Cloudflare's KV storage for state management and integrates with external OAuth and Stripe services via HTTP APIs. Requests flow through a central /sse endpoint that handles Server-Sent Events for real-time tool execution and response streaming.

Implements a dual-provider OAuth authentication system using the OAuthProvider class that verifies user identity through Google or GitHub. Authentication tokens are stored in Cloudflare KV storage (OAUTH_KV) and validated on each request. The system handles the OAuth redirect flow, token exchange, and session management without requiring users to create new credentials.

Validates tool inputs against JSON Schema definitions before execution, ensuring that only well-formed requests reach tool handlers. The system compares incoming tool parameters against the tool's declared inputSchema, rejects invalid inputs with detailed error messages, and prevents malformed requests from causing tool failures. Validation happens automatically as part of the tool execution pipeline.

Implements the Model Context Protocol (MCP) specification, allowing AI assistants to discover available tools, inspect their schemas, and invoke them dynamically. The system exposes tool metadata (name, description, input schema) via MCP protocol messages, handles tool invocation requests, and returns results in MCP-compliant format. This enables seamless integration with MCP-compatible clients like Claude and Cursor.

Orchestrates the complete request lifecycle from initial connection through authentication, payment validation, tool execution, and response streaming. The system validates OAuth tokens, checks payment status (if applicable), validates tool inputs, executes the tool handler, and streams results via SSE. Each step is enforced in sequence — requests fail fast if authentication or payment checks fail, preventing unnecessary tool execution.

Provides structured error handling throughout the request lifecycle, returning detailed error messages for authentication failures, payment validation failures, input validation errors, and tool execution errors. Errors are formatted as JSON responses or SSE messages, allowing AI assistants to understand what went wrong and potentially retry or adjust their requests. Error messages include context (which step failed, why) without leaking sensitive information.

Integrates Stripe payment processing through the PaidMcpAgent class, supporting three distinct payment models: subscription-based (recurring charges), metered usage (pay-per-use), and one-time payments. Before a user accesses a paid tool, the system checks their payment status via Stripe API; unpaid users receive a checkout URL. Payment history and subscription status are tracked and validated on each tool invocation.

Provides a declarative tool registration system where developers define tools (free or paid) with metadata including name, description, input schema, and payment model. The BoilerplateMCP class (extending PaidMcpAgent) manages tool registration, validates input against schemas, executes tool handlers, and enforces payment requirements. Tools are exposed via the MCP protocol, allowing AI assistants to discover and invoke them dynamically.

Implements a subscription payment model where users pay recurring fees (monthly, yearly, etc.) for continuous access to tools. The system checks Stripe subscription status on each tool invocation; active subscriptions grant access, while expired or canceled subscriptions deny access and provide a renewal checkout URL. Subscription state is validated against Stripe's authoritative records, not cached locally.

Implements a metered billing model where users are charged based on actual tool usage (e.g., per API call, per unit processed). Developers submit usage events to Stripe, which aggregates them and charges users according to configured meter rates. Access control checks whether the user has an active metered billing subscription; usage is tracked separately and billed at the end of the billing cycle.

Implements a one-time payment model where users pay once for permanent or perpetual access to a tool. After payment is confirmed, the system records the purchase in Stripe and grants indefinite access without requiring renewal. Access control checks whether a user has completed the one-time payment; if not, they receive a checkout URL.

Implements the /sse endpoint using Server-Sent Events to stream tool execution results back to AI assistants in real-time. The system establishes a persistent connection, executes tools, and sends results as SSE-formatted messages. This allows AI assistants to receive tool outputs incrementally rather than waiting for complete execution, enabling responsive interactions.

Uses Cloudflare KV (key-value store) as the primary data store for OAuth tokens, user sessions, and payment state. The system stores authentication tokens with optional TTL, retrieves them on subsequent requests, and manages user session lifecycle. KV provides distributed, edge-local storage without requiring external databases, but with eventual consistency guarantees rather than strong consistency.

Supports environment-specific configuration through environment variables and wrangler.toml settings, allowing developers to deploy the same codebase to development, staging, and production with different configurations. Variables include OAuth credentials, Stripe keys, KV namespace bindings, and deployment targets. The system reads configuration at Worker initialization time and uses it throughout the request lifecycle.