Cloudflare MCP Template

A reusable template for creating Cloudflare Workers that serve Model Context Protocol (MCP) servers with a provider plugin system.

Why I built this

In October 2025 the MCP specification added OAuth 2.1 with Dynamic Client Registration — meaning Claude.ai could connect to MCP servers without users manually configuring OAuth credentials. Almost no public templates implemented this correctly. I built this to capture that pattern before it became standard: stateless edge deployment on Cloudflare Workers, a clean provider plugin interface so any REST API can be wired in under 30 minutes, and full OAuth 2.1 compliance out of the box. The goal was a template I could clone and have a production MCP server running in under an hour.

Architecture

flowchart TD
    A["Claude.ai / MCP Client"] -->|HTTP · Streamable MCP transport| B

    subgraph B["Cloudflare Worker"]
        direction TB
        C["OAuth 2.1 DCR\n/register"]
        D["MCP Transport\ntools/list · tools/call"] --> E["Provider Plugin\nMCPProvider API"]
    end

    E --> F["External REST API\nTodoist · GitHub · Notion · …"]

    style B fill:#1a1a2e,stroke:#f38020,stroke-width:2px
    style A fill:#2d1b69,stroke:#8b5cf6,color:#fff
    style C fill:#1e3a5f,stroke:#3178c6,color:#fff
    style D fill:#1e3a5f,stroke:#3178c6,color:#fff
    style E fill:#1e3a5f,stroke:#3178c6,color:#fff
    style F fill:#1a3a2e,stroke:#22c55e,color:#fff

🚀 Quick Start

git clone https://github.com/mahmoudfazeli/cloudflare-mcp-template.git
cd cloudflare-mcp-template

mkdir ../your-mcp-project
cp -r template/* ../your-mcp-project/
cd ../your-mcp-project/

sed 's/{{PROJECT_NAME}}/your-project-name/g' package.json.template > package.json
sed 's/{{PROJECT_NAME}}/your-project-name/g' wrangler.toml.template > wrangler.toml

npm install
npm run setup-oauth   # creates KV namespaces for OAuth credential storage
npm run dev           # http://localhost:8787

🎯 What You Get

🔌 Provider Plugin System

• Easy API integration: implement MCPProvider to connect any REST API
• Example provider: working ping/echo/status tools out of the box
• Clean interfaces: MCPProvider and MCPServerFactory patterns

🔐 OAuth 2.1 — Zero Config for Claude.ai

• Dynamic Client Registration: Claude.ai connects without manual OAuth setup
• MCP spec compliant: follows the March 2026 authorization specification
• KV-backed credential storage: isolated per environment

🏗️ Production-Ready

• Stateless transport: no session persistence, scales to zero
• Multi-environment: project-dev / project-staging / project stable naming
• TypeScript strict: full type safety with Zod schemas on tool parameters
• SemVer + git metadata: injected at build time, no runtime FS access

🔧 Creating a Provider

1. Create src/providers/your-service/ with three files:
   • api.ts — REST API client
   • factory.ts — register MCP tools with Zod schemas
   • index.ts — export the MCPProvider object
2. Update worker.ts to import your provider (one line change)
3. Run npm run dev and curl /mcp

See docs/PROVIDERS.md for a full walkthrough.

🌍 Environments

npm run deploy:development   # → your-project-dev.workers.dev
npm run deploy:staging       # → your-project-staging.workers.dev
npm run deploy:production    # → your-project.workers.dev

📖 Docs

• USAGE.md — curl examples and local testing
• PROVIDERS.md — building custom providers
• CLAUDE.md — Claude Code integration

License

MIT