cloudflare-mcp-server

What this skill does

# Cloudflare MCP Server Skill

Build and deploy **Model Context Protocol (MCP) servers** on Cloudflare Workers with TypeScript.

---

## What is This Skill?

This skill teaches you to build **remote MCP servers** on Cloudflare - the ONLY platform with official remote MCP support as of 2025.

**Use this skill when**:
- Building MCP servers with TypeScript (@modelcontextprotocol/sdk)
- Deploying remote MCP servers to Cloudflare Workers
- Implementing OAuth authentication (GitHub, Google, Azure, custom)
- Creating stateful MCP servers with Durable Objects
- Optimizing costs with WebSocket hibernation
- Supporting both SSE and Streamable HTTP transports
- Avoiding 22+ common MCP + Cloudflare errors (especially URL path mismatches!)

**You'll learn**:
1. **HTTP transport fundamentals** (URL path configuration, routing)
2. **Transport selection** (SSE vs Streamable HTTP)
3. McpAgent class patterns and tool definitions
4. OAuth integration (all 5 auth patterns)
5. Cloudflare service integrations (Workers AI, D1, Vectorize, etc.)
6. Durable Objects for per-session state
7. WebSocket hibernation API
8. Complete deployment workflow

---

## 🚀 Official Cloudflare Templates (Start Here!)

**Before using this skill's templates**, know that Cloudflare provides **official starter templates** via `npm create`.

### Recommended Starting Point

**For most projects, start with Cloudflare's official authless template:**

```bash
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-authless

cd my-mcp-server
npm install
npm run dev
```

**What you get:**
- ✅ Minimal working MCP server (~50 lines)
- ✅ Dual transport support (SSE + Streamable HTTP)
- ✅ Pre-configured wrangler.jsonc
- ✅ Ready to deploy immediately

**Then customize with patterns from this skill** to avoid the 22+ common errors!

---

### All Available Cloudflare Templates

Cloudflare maintains 14+ official MCP templates. Use these as starting points:

#### Basic Templates

| Template Command | Purpose | When to Use |
|-----------------|---------|-------------|
| `--template=cloudflare/ai/demos/remote-mcp-authless` | **Gold standard starter** - No auth, simple tools | New projects, learning, public APIs |
| `--template=cloudflare/ai/demos/remote-mcp-github-oauth` | GitHub OAuth + Workers AI | Developer tools, GitHub integrations |
| `--template=cloudflare/ai/demos/remote-mcp-google-oauth` | Google OAuth | Google Workspace integration |

#### Advanced Authentication Templates

| Template Command | Auth Method | Use Case |
|-----------------|-------------|----------|
| `--template=cloudflare/ai/demos/remote-mcp-auth0` | Auth0 | Enterprise SSO |
| `--template=cloudflare/ai/demos/remote-mcp-authkit` | WorkOS AuthKit | B2B SaaS applications |
| `--template=cloudflare/ai/demos/remote-mcp-logto` | Logto | Open-source auth |
| `--template=cloudflare/ai/demos/remote-mcp-cf-access` | Cloudflare Access | Internal company tools |
| `--template=cloudflare/ai/demos/mcp-server-bearer-auth` | Bearer tokens | Custom auth systems |

#### Integration Examples

| Template Command | Demonstrates | Cloudflare Services |
|-----------------|--------------|---------------------|
| `--template=cloudflare/ai/demos/remote-mcp-server-autorag` | RAG (Retrieval-Augmented Generation) | Workers AI + Vectorize |
| `--template=cloudflare/ai/demos/python-workers-mcp` | Python MCP servers | Python Workers |

---

### When to Use This Skill's Templates

**Use this skill's templates when:**
- Learning how URL paths work (use `mcp-http-fundamentals.ts`)
- Need comprehensive error prevention (all templates include warnings)
- Want detailed comments explaining every decision
- Building complex integrations (Workers AI, D1, Bearer auth)

**This skill's templates are MORE educational** than Cloudflare's (more comments, defensive patterns, error handling).

**Cloudflare's templates are FASTER to start** with (minimal, production-ready).

**Best approach**: Start with Cloudflare's template, then reference this skill to avoid errors!

---

### Production MCP Servers (Study These!)

Cloudflare maintains **15 production MCP servers** showing real-world integration patterns:

**Key servers to study:**
- `workers-bindings` - D1, KV, R2, AI, Durable Objects usage
- `browser-rendering` - Web scraping + screenshot tools
- `autorag` - Vectorize RAG pattern
- `ai-gateway` - Workers AI Gateway analytics
- `docs` - Cloudflare documentation search

**Repository**: https://github.com/cloudflare/mcp-server-cloudflare

**Why study these?** They show production-grade patterns for:
- Error handling
- Rate limiting
- Caching strategies
- Real API integrations
- Security best practices

---

## 🎯 Quick Start Workflow (Your Step-by-Step Guide)

**Follow this workflow for your next MCP server to avoid errors and ship fast.**

---

### Step 1: Choose Your Starting Template

**Decision tree:**

```
What are you building?

├─ 🆓 Public/dev server (no auth needed)
│  └─> Use: remote-mcp-authless ⭐ RECOMMENDED FOR MOST PROJECTS
│
├─ 🔐 GitHub integration
│  └─> Use: remote-mcp-github-oauth (includes Workers AI example)
│
├─ 🔐 Google Workspace integration
│  └─> Use: remote-mcp-google-oauth
│
├─ 🏢 Enterprise SSO (Auth0, Okta, etc.)
│  └─> Use: remote-mcp-auth0 or remote-mcp-authkit
│
├─ 🔑 Custom auth system / API keys
│  └─> Start with authless, then add bearer auth (see Step 3)
│
└─ 🏠 Internal company tool
   └─> Use: remote-mcp-cf-access (Cloudflare Zero Trust)
```

**Not sure?** Start with `remote-mcp-authless` - you can add auth later!

---

### Step 2: Create from Template

```bash
# Replace [TEMPLATE] with your choice from Step 1
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/[TEMPLATE]

# Example: authless template (most common)
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-authless

# Navigate and install
cd my-mcp-server
npm install

# Start dev server
npm run dev
```

**Your MCP server is now running at**: `http://localhost:8788/sse`

---

### Step 3: Customize with This Skill's Patterns

**Now add features by copying patterns from this skill:**

#### Need Workers AI (image/text generation)?
```bash
# Copy our Workers AI template
cp ~/.claude/skills/cloudflare-mcp-server/templates/mcp-with-workers-ai.ts src/my-ai-tools.ts

# Add AI binding to wrangler.jsonc:
# { "ai": { "binding": "AI" } }
```

**Tools you get**: `generate_image`, `generate_text`, `list_ai_models`

---

#### Need a database (D1)?
```bash
# Copy our D1 template
cp ~/.claude/skills/cloudflare-mcp-server/templates/mcp-with-d1.ts src/my-db-tools.ts

# Create D1 database:
npx wrangler d1 create my-database

# Add binding to wrangler.jsonc
```

**Tools you get**: `create_user`, `get_user`, `list_users`, `update_user`, `delete_user`, `search_users`

---

#### Need bearer token auth?
```bash
# Copy our bearer auth template
cp ~/.claude/skills/cloudflare-mcp-server/templates/mcp-bearer-auth.ts src/index.ts

# Add token validation (KV, external API, or static)
```

**What you get**: Authorization header middleware, token validation, authenticated tools

---

### Step 4: Deploy to Cloudflare

```bash
# Login (first time only)
npx wrangler login

# Deploy to production
npx wrangler deploy
```

**Output shows your deployed URL**:
```
✨ Deployment complete!
https://my-mcp-server.YOUR_ACCOUNT.workers.dev
```

**⚠️ CRITICAL: Note this URL - you'll need it in Step 5!**

---

### Step 5: Test & Configure Client

#### A. Test with curl (PREVENTS 80% OF ERRORS!)

```bash
# Test the exact URL you'll use in client config
curl https://my-mcp-server.YOUR_ACCOUNT.workers.dev/sse
```

**Expected response**:
```json
{
  "name": "My MCP Server",
  "version": "1.0.0",
  "transports": ["/sse", "/mcp"]
}
```

**Got 404?** → Your client URL will be wrong! See "HTTP Transport Fundamentals" below.

---

#### B. Update Claude Desktop Config

**Linux/Mac**: `~/.config/claude/claude_desktop_config.json`
**Windows**