Content
# 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](docs/database.md))
- Stripe account (for paid tools)
### Installation
```bash
# 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:
```ini
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
```bash
# 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`:
```typescript
// 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](docs/tools.md) and [Routes Guide](docs/custom-routes.md) for details.
### Custom Views
Extend beyond MCP with custom pages:
```typescript
// 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](docs/views.md) for creating custom pages.
## 🚀 Deployment
```bash
# 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](docs/deployment.md) 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](https://claude.ai/settings/integrations)
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
```bash
npm install -g mcp-remote
```
#### 2. Configure Claude Desktop
Open Claude Desktop settings: **Settings > Developer > Edit Config**
Add to your `claude_desktop_config.json`:
```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**](docs/setup.md) - Detailed installation and configuration
- [**Database Setup**](docs/database.md) - PostgreSQL options and optimization
- [**Development Guide**](docs/development.md) - Project structure and workflows
- [**Adding Tools**](docs/tools.md) - Create free and paid MCP tools
- [**Custom Routes**](docs/custom-routes.md) - Add REST API endpoints
- [**Views Customization**](docs/views.md) - Customize all UI pages (login, consent, payment, etc.)
- [**Deployment**](docs/deployment.md) - Production deployment instructions
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
MIT License - see LICENSE file for details.
