Building MCP Servers on Cloudflare

Your knowledge of the MCP SDK and Cloudflare Workers integration may be outdated. Prefer retrieval over pre-training for any MCP server task.

Retrieval Sources

When to Use

• User wants to build a remote MCP server
• User needs to expose tools via MCP
• User asks about MCP authentication or OAuth
• User wants to deploy MCP to Cloudflare Workers

Prerequisites

• Cloudflare account with Workers enabled
• Node.js 18+ and npm/pnpm/yarn
• Wrangler CLI (npm install -g wrangler)

Quick Start

Option 1: Public Server (No Auth)

bash
1npm create cloudflare@latest -- my-mcp-server \
2  --template=cloudflare/ai/demos/remote-mcp-authless
3cd my-mcp-server
4npm start

Server runs at http://localhost:8788/mcp

Option 2: Authenticated Server (OAuth)

bash
1npm create cloudflare@latest -- my-mcp-server \
2  --template=cloudflare/ai/demos/remote-mcp-github-oauth
3cd my-mcp-server

Requires OAuth app setup. See references/oauth-setup.md.

Core Workflow

Step 1: Define Tools

Tools are functions MCP clients can call. Define them using server.tool():

typescript
1import { McpAgent } from "agents/mcp";
2import { z } from "zod";
3
4export class MyMCP extends McpAgent {
5  server = new Server({ name: "my-mcp", version: "1.0.0" });
6
7  async init() {
8    // Simple tool with parameters
9    this.server.tool(
10      "add",
11      { a: z.number(), b: z.number() },
12      async ({ a, b }) => ({
13        content: [{ type: "text", text: String(a + b) }],
14      })
15    );
16
17    // Tool that calls external API
18    this.server.tool(
19      "get_weather",
20      { city: z.string() },
21      async ({ city }) => {
22        const response = await fetch(`https://api.weather.com/${city}`);
23        const data = await response.json();
24        return {
25          content: [{ type: "text", text: JSON.stringify(data) }],
26        };
27      }
28    );
29  }
30}

Step 2: Configure Entry Point

Public server (src/index.ts):

typescript
1import { MyMCP } from "./mcp";
2
3export default {
4  fetch(request: Request, env: Env, ctx: ExecutionContext) {
5    const url = new URL(request.url);
6    if (url.pathname === "/mcp") {
7      return MyMCP.serveSSE("/mcp").fetch(request, env, ctx);
8    }
9    return new Response("MCP Server", { status: 200 });
10  },
11};
12
13export { MyMCP };

Authenticated server — See references/oauth-setup.md.

Step 3: Test Locally

bash
1# Start server
2npm start
3
4# In another terminal, test with MCP Inspector
5npx @modelcontextprotocol/inspector@latest
6# Open http://localhost:5173, enter http://localhost:8788/mcp

Step 4: Deploy

bash
1npx wrangler deploy

Server accessible at https://[worker-name].[account].workers.dev/mcp

Step 5: Connect Clients

Claude Desktop (claude_desktop_config.json):

json
1{
2  "mcpServers": {
3    "my-server": {
4      "command": "npx",
5      "args": ["mcp-remote", "https://my-mcp.workers.dev/mcp"]
6    }
7  }
8}

Restart Claude Desktop after updating config.

Tool Patterns

Return Types

typescript
1// Text response
2return { content: [{ type: "text", text: "result" }] };
3
4// Multiple content items
5return {
6  content: [
7    { type: "text", text: "Here's the data:" },
8    { type: "text", text: JSON.stringify(data, null, 2) },
9  ],
10};

Input Validation with Zod

typescript
1this.server.tool(
2  "create_user",
3  {
4    email: z.string().email(),
5    name: z.string().min(1).max(100),
6    role: z.enum(["admin", "user", "guest"]),
7    age: z.number().int().min(0).optional(),
8  },
9  async (params) => {
10    // params are fully typed and validated
11  }
12);

Accessing Environment/Bindings

typescript
1export class MyMCP extends McpAgent<Env> {
2  async init() {
3    this.server.tool("query_db", { sql: z.string() }, async ({ sql }) => {
4      // Access D1 binding
5      const result = await this.env.DB.prepare(sql).all();
6      return { content: [{ type: "text", text: JSON.stringify(result) }] };
7    });
8  }
9}

Authentication

For OAuth-protected servers, see references/oauth-setup.md.

Supported providers:

• GitHub
• Google
• Auth0
• Stytch
• WorkOS
• Any OAuth 2.0 compliant provider

Wrangler Configuration

Minimal wrangler.toml:

toml
1name = "my-mcp-server"
2main = "src/index.ts"
3compatibility_date = "2024-12-01"
4
5[durable_objects]
6bindings = [{ name = "MCP", class_name = "MyMCP" }]
7
8[[migrations]]
9tag = "v1"
10new_classes = ["MyMCP"]

With bindings (D1, KV, etc.):

toml
1[[d1_databases]]
2binding = "DB"
3database_name = "my-db"
4database_id = "xxx"
5
6[[kv_namespaces]]
7binding = "KV"
8id = "xxx"

Common Issues

"Tool not found" in Client

1. Verify tool name matches exactly (case-sensitive)
2. Ensure init() registers tools before connections
3. Check server logs: wrangler tail

Connection Fails

1. Confirm endpoint path is /mcp
2. Check CORS if browser-based client
3. Verify Worker is deployed: wrangler deployments list

OAuth Redirect Errors

1. Callback URL must match OAuth app config exactly
2. Check GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set
3. For local dev, use http://localhost:8788/callback

References

• references/examples.md — Official templates and production examples
• references/oauth-setup.md — OAuth provider configuration
• references/tool-patterns.md — Advanced tool examples
• references/troubleshooting.md — Error codes and fixes