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 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
```typescript
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**:
```typescript
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:
```typescript
MyMCP.serveSSE("/sse").fetch(request, env, ctx)
```

**Streamable HTTP** - 2025 standard, more efficient:
```typescript
MyMCP.serve("/mcp").fetch(request, env, ctx)
```

**Support both** for maximum compatibility:
```typescript
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**:
```typescript
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**:
```typescript
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**:
```jsonc
{
  "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**:
```typescript
await this.state.storage.put("key", "value");
await this.state.storage.put("user_prefs", { theme: "dark" });
```

**Retrieve values**:
```typescript
const value = await this.state.storage.get<string>("key");
const prefs = await this.state.storage.get<object>("user_prefs");
```

**List keys**:
```typescript
const allKeys = await this.state.storage.list();
```

**Delete keys**:
```typescript
await this.state.storage.delete("key");
```

### Configuration

**wrangler.jsonc**:
```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_MCP",
        "class_name": "MyMCP",
        "script_name": "my-mcp-server"
      }
    ]
  },

  "migrations": [