What is Mcp Startup Framework

The MCP Startup Framework is a comprehensive toolkit for building remote Model Context Protocol (MCP) servers, featuring OAuth authentication, PostgreSQL integration, and payment systems through Stripe. It is designed to be modular and adaptable, making it suitable for various deployment environments.

Use cases

It’s suitable for creating applications that require user authentication, subscription-based services, and integration with remote tools. Potential applications include personal productivity tools, collaborative systems, or any service needing a secure, user-context-driven architecture.

How to use

After setting up the environment with Node.js and PostgreSQL, clone the repository and configure your settings in the ‘.dev.vars’ file. Use npm commands to run the development server and initialize the database. You can register tools and add custom REST API routes by modifying ‘src/index.ts’. Deployment to Cloudflare Workers or other platforms can be accomplished using specific commands to set environment variables and deploy the application.

Key features

Key features include OAuth 2.1 for user authentication, PostgreSQL for database management, Stripe for payment processing, a modular tool system for easy extension, customizable REST API routes, and an interface for adding custom views. It also supports multiple transport protocols for integration with various client applications.

Where to use

While optimized for Cloudflare Workers, the framework is versatile and can be deployed on various platforms such as Vercel, Railway, AWS Lambda, Google Cloud Run, or even self-hosted environments. It can also be utilized with several PostgreSQL providers including Neon, Supabase, and Amazon RDS, making it suitable for production-level applications.

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.