cloudflare-mcp-server

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 15+ common MCP + Cloudflare errors

You'll learn:

1. McpAgent class patterns and tool definitions
2. OAuth integration (all 4 auth patterns)
3. Durable Objects for per-session state
4. WebSocket hibernation API
5. Dual transport configuration (SSE + HTTP)
6. Complete deployment workflow

Quick Start (5 Minutes)

Option 1: Deploy from Template

# Create new MCP server from Cloudflare template
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-authless

cd my-mcp-server
npm install
npm run dev

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

Option 2: Copy Templates from This Skill

# Copy basic MCP server template
cp ~/.claude/skills/cloudflare-mcp-server/templates/basic-mcp-server.ts src/index.ts
cp ~/.claude/skills/cloudflare-mcp-server/templates/wrangler-basic.jsonc wrangler.jsonc
cp ~/.claude/skills/cloudflare-mcp-server/templates/package.json package.json

# Install dependencies
npm install

# Start development server
npm run dev

Test with MCP Inspector

# In a new terminal, start MCP Inspector
npx @modelcontextprotocol/inspector@latest

# Open http://localhost:5173
# Enter your MCP server URL: http://localhost:8788/sse
# Click "Connect" and test tools

Deploy to Cloudflare

# Deploy to production
npx wrangler deploy

# Your MCP server is now live at:
# https://my-mcp-server.your-account.workers.dev/sse

Core Concepts

1. McpAgent Class

The McpAgent base class from Cloudflare's Agents SDK provides:

• Automatic Durable Objects integration
• Built-in state management with SQL database
• Tool, resource, and prompt registration
• Transport handling (SSE + HTTP)

Basic pattern:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent<Env> {
  server = new McpServer({
    name: "My MCP Server",
    version: "1.0.0"
  });

  async init() {
    // Register tools here
    this.server.tool(
      "tool_name",
      "Tool description",
      { param: z.string() },
      async ({ param }) => ({
        content: [{ type: "text", text: "Result" }]
      })
    );
  }
}

2. Tool Definitions

Tools are functions that MCP clients can invoke. Use Zod for parameter validation.

Pattern:

this.server.tool(
  "tool_name",           // Tool identifier
  "Tool description",    // What it does (for LLM)
  {                      // Parameters (Zod schema)
    param1: z.string().describe("Parameter description"),
    param2: z.number().optional()
  },
  async ({ param1, param2 }) => {  // Handler
    // Your logic here
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Best practices:

• Detailed descriptions: Help LLMs understand tool purpose
• Parameter descriptions: Explain expected values and constraints
• Error handling: Return { isError: true } for failures
• Few, focused tools: Better than many granular ones

3. Transport Methods

MCP supports two transports:

SSE (Server-Sent Events) - Legacy, widely supported:

MyMCP.serveSSE("/sse").fetch(request, env, ctx)

Streamable HTTP - 2025 standard, more efficient:

MyMCP.serve("/mcp").fetch(request, env, ctx)

Support both for maximum compatibility:

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const { pathname } = new URL(request.url);

    if (pathname.startsWith("/sse")) {
      return MyMCP.serveSSE("/sse").fetch(request, env, ctx);
    }
    if (pathname.startsWith("/mcp")) {
      return MyMCP.serve("/mcp").fetch(request, env, ctx);
    }

    return new Response("Not Found", { status: 404 });
  }
};

Authentication Patterns

Cloudflare MCP servers support 4 authentication patterns:

Pattern 1: No Authentication

Use case: Internal tools, development, public APIs

Template: templates/basic-mcp-server.ts

Setup: None required

Security: ⚠️ Anyone can access your MCP server

Pattern 2: Token Validation (JWTVerifier)

Use case: Pre-authenticated clients, custom auth systems

How it works: Client sends Bearer token, server validates

Template: Create custom JWTVerifier middleware

Setup:

import { JWTVerifier } from "agents/mcp";

const verifier = new JWTVerifier({
  secret: env.JWT_SECRET,
  issuer: "your-auth-server"
});

// Validate token before serving MCP requests

Security: ✅ Secure if tokens are properly managed

Pattern 3: OAuth Proxy (workers-oauth-provider)

Use case: GitHub, Google, Azure OAuth integration

How it works: Cloudflare Worker proxies OAuth to third-party provider

Template: templates/mcp-oauth-proxy.ts

Setup:

import { OAuthProvider, GitHubHandler } from "@cloudflare/workers-oauth-provider";

export default new OAuthProvider({
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",

  defaultHandler: new GitHubHandler({
    clientId: (env) => env.GITHUB_CLIENT_ID,
    clientSecret: (env) => env.GITHUB_CLIENT_SECRET,
    scopes: ["repo", "user:email"],

    context: async (accessToken) => {
      // Fetch user info from GitHub
      const octokit = new Octokit({ auth: accessToken });
      const { data: user } = await octokit.rest.users.getAuthenticated();

      return {
        login: user.login,
        email: user.email,
        accessToken
      };
    }
  }),

  kv: (env) => env.OAUTH_KV,
  apiHandlers: {
    "/sse": MyMCP.serveSSE("/sse"),
    "/mcp": MyMCP.serve("/mcp")
  },

  allowConsentScreen: true,
  allowDynamicClientRegistration: true
});

Required bindings:

{
  "kv_namespaces": [
    { "binding": "OAUTH_KV", "id": "YOUR_KV_ID" }
  ]
}

Security: ✅✅ Secure, production-ready

Pattern 4: Remote OAuth with DCR

Use case: Full OAuth provider, custom consent screens

How it works: Your Worker is the OAuth provider

Template: See Cloudflare's remote-mcp-authkit demo

Setup: Complex, requires full OAuth 2.1 implementation

Security: ✅✅✅ Most secure, full control

Stateful MCP Servers with Durable Objects

Use Durable Objects when your MCP server needs:

• Per-session persistent state
• Conversation history
• Game state (chess, tic-tac-toe)
• Cached API responses
• User preferences

Storage API Pattern

Template: templates/mcp-stateful-do.ts

Store values:

await this.state.storage.put("key", "value");
await this.state.storage.put("user_prefs", { theme: "dark" });

Retrieve values:

const value = await this.state.storage.get<string>("key");
const prefs = await this.state.storage.get<object>("user_prefs");

List keys:

const allKeys = await this.state.storage.list();

Delete keys:

await this.state.storage.delete("key");

Configuration

wrangler.jsonc:

{
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_MCP",
        "class_name": "MyMCP",
        "script_name": "my-mcp-server"
      }
    ]
  },

  "migrations": [
    {