What is Mcp Cloudflare Boilerplate

mcp-cloudflare-boilerplate is a comprehensive boilerplate for developing remote Model Context Protocol (MCP) servers using Cloudflare Workers. It includes custom OAuth authentication and PostgreSQL database integration, providing a solid foundation for building production-ready applications.

Use cases

Use cases include building user authentication systems, creating data-driven applications, implementing custom APIs for mobile and web clients, and developing tools that require user context and personalized interactions.

How to use

To use mcp-cloudflare-boilerplate, start by configuring your main file at src/index.ts. You can register MCP tools and add custom REST API endpoints easily. Follow the quick start guide in the README for initial setup and deployment instructions.

Key features

Key features include a complete OAuth 2.1 provider, PostgreSQL integration, serverless deployment with Cloudflare Workers, a modular MCP tools framework, customizable REST API routes, a responsive UI, robust security measures, mobile readiness, and developer-friendly TypeScript support.

Where to use

mcp-cloudflare-boilerplate can be used in various fields such as web applications, mobile apps, and any platform requiring secure user authentication and data management through a scalable server architecture.

MCP Startup Framework

A complete framework for building remote Model Context Protocol (MCP) servers on Cloudflare Workers with OAuth authentication, PostgreSQL database, and Stripe-powered paid tools.

🚀 Features

• 🔐 OAuth 2.1 Provider - Complete authentication with user registration/login
• 🗄️ PostgreSQL Integration - Scalable production-ready database with connection pooling
• 💳 Paid Tools Framework - Stripe-powered premium tools with subscription support
• 🌐 Platform Agnostic - Optimized for Cloudflare Workers but deployable anywhere (Vercel, Railway, AWS, self-hosted)
• 🛠️ MCP Tools Framework - Modular tool system with user context
• 🔌 REST API Routes - Easy-to-use system for adding custom endpoints
• 🎨 Custom Views - Extensible UI system for privacy policies, ToS, documentation pages
• 📡 Streamable HTTP Transport - Works with mcp-remote for local Claude Desktop integration
• 📱 Cross-Platform - Works on desktop, web, and mobile MCP clients

⚡ Quick Start

Prerequisites

• Node.js 18+
• Cloudflare account
• PostgreSQL database (see database setup)
• Stripe account (for paid tools)

Installation

# Clone the repository
git clone https://github.com/f/mcp-startup-framework
cd mcp-startup-framework

# Install dependencies
npm install

# Copy environment template
cp .dev.vars.example .dev.vars

Configuration

Edit .dev.vars with your settings:

DATABASE_URL="postgresql://username:password@host:port/database"
JWT_SECRET="your-super-secret-jwt-key"
COOKIE_ENCRYPTION_KEY="32-character-encryption-key"
STRIPE_SECRET_KEY="sk_test_your_stripe_key"
STRIPE_PRICE_ID_FOR_PREMIUM_MATH="price_your_stripe_price_id"
BASE_URL="https://your-domain.workers.dev"

Development

# Start development server
npm run dev

# Initialize database (in another terminal)
curl -X POST http://localhost:8787/init-db

# Visit http://localhost:8787 to register/login

🛠️ Adding Tools & Routes

Everything starts from src/index.ts:

// Register MCP tools
backend
  .registerTool(registerAddTool)
  .registerTool(registerGreetingTool)
  .registerTool(registerPremiumMathTool);

// Add REST API routes
backend
  .route('GET', '/api/status', (c) => c.json({ status: 'ok' }))
  .authRoute('GET', '/api/profile', (c, userContext) => 
    c.json({ user: userContext })
  );

See Tools Guide and Routes Guide for details.

Custom Views

Extend beyond MCP with custom pages:

// Add privacy policy, terms of service, documentation
backend
  .route('GET', '/privacy', (c) => c.html(generatePrivacyPage()))
  .route('GET', '/terms', (c) => c.html(generateTermsPage()))
  .route('GET', '/docs', (c) => c.html(generateDocsPage()));

See Views Guide for creating custom pages.

🚀 Deployment

# Set production secrets
wrangler secret put JWT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put STRIPE_SECRET_KEY

# Set custom price IDs per paid tool
wrangler secret put STRIPE_PRICE_ID_FOR_PREMIUM_MATH

# Deploy to Cloudflare
npm run deploy

See Deployment Guide for full instructions.

🔗 Integration Options

Using claude.ai (Pro Plan)

For claude.ai Pro users, you can integrate directly:

1. Navigate to claude.ai settings
2. Click “Add Integration”
3. Enter your server URL: https://your-domain.workers.dev/sse
4. Complete the OAuth flow

Using Claude Desktop

For local Claude Desktop app:

1. Install MCP Remote Client

npm install -g mcp-remote

2. Configure Claude Desktop

Open Claude Desktop settings: Settings > Developer > Edit Config

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-startup": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-domain.workers.dev/mcp"
      ]
    }
  }
}

3. Restart Claude Desktop

After saving, restart Claude Desktop. Your MCP tools will appear in the chat interface.

Transport Options

The framework supports multiple transport protocols:

• Streamable HTTP (default) - /mcp endpoint
• Server-Sent Events (SSE) - /sse endpoint

Both work seamlessly with mcp-remote for local development and production use.

🌐 Platform Flexibility

While optimized for Cloudflare Workers, this framework runs anywhere:

• Vercel: Deploy with @vercel/node runtime
• Railway: One-click deploy with built-in PostgreSQL
• AWS Lambda: Use with RDS or Aurora Serverless
• Google Cloud Run: Deploy with Cloud SQL
• Self-hosted: Run with Docker on any VPS

Simply update your database connection and deployment configuration!

Production Database

The framework works with any PostgreSQL provider:

• Neon - Serverless PostgreSQL with autoscaling
• Supabase - PostgreSQL with real-time features
• Railway - Managed PostgreSQL with automatic backups
• Amazon RDS - Enterprise-grade PostgreSQL
• Cloudflare Hyperdrive - Connection pooling for optimal performance

All providers support the scalability needed for production MCP servers.

📚 Documentation

• Setup Guide - Detailed installation and configuration
• Database Setup - PostgreSQL options and optimization
• Development Guide - Project structure and workflows
• Adding Tools - Create free and paid MCP tools
• Custom Routes - Add REST API endpoints
• Views Customization - Customize all UI pages (login, consent, payment, etc.)
• Deployment - Production deployment instructions

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.