Building MCP Server On Cloudflare

1---
2name: building-mcp-server-on-cloudflare
3description: |
4  Builds remote MCP (Model Context Protocol) servers on Cloudflare Workers
5  with tools, OAuth authentication, and production deployment. Generates
6  server code, configures auth providers, and deploys to Workers.
7 
8  Use when: user wants to "build MCP server", "create MCP tools", "remote
9  MCP", "deploy MCP", add "OAuth to MCP", or mentions Model Context Protocol
10  on Cloudflare. Also triggers on "MCP authentication" or "MCP deployment".
11---
12 
13# Building MCP Servers on Cloudflare
14 
15Creates production-ready Model Context Protocol servers on Cloudflare Workers with tools, authentication, and deployment.
16 
17## When to Use
18 
19- User wants to build a remote MCP server
20- User needs to expose tools via MCP
21- User asks about MCP authentication or OAuth
22- User wants to deploy MCP to Cloudflare Workers
23 
24## Prerequisites
25 
26- Cloudflare account with Workers enabled
27- Node.js 18+ and npm/pnpm/yarn
28- Wrangler CLI (`npm install -g wrangler`)
29 
30## Quick Start
31 
32### Option 1: Public Server (No Auth)
33 
34```bash
35npm create cloudflare@latest -- my-mcp-server \
36  --template=cloudflare/ai/demos/remote-mcp-authless
37cd my-mcp-server
38npm start
39```
40 
41Server runs at `http://localhost:8788/mcp`
42 
43### Option 2: Authenticated Server (OAuth)
44 
45```bash
46npm create cloudflare@latest -- my-mcp-server \
47  --template=cloudflare/ai/demos/remote-mcp-github-oauth
48cd my-mcp-server
49```
50 
51Requires OAuth app setup. See [references/oauth-setup.md](references/oauth-setup.md).
52 
53## Core Workflow
54 
55### Step 1: Define Tools
56 
57Tools are functions MCP clients can call. Define them using `server.tool()`:
58 
59```typescript
60import { McpAgent } from "agents/mcp";
61import { z } from "zod";
62 
63export class MyMCP extends McpAgent {
64  server = new Server({ name: "my-mcp", version: "1.0.0" });
65 
66  async init() {
67    // Simple tool with parameters
68    this.server.tool(
69      "add",
70      { a: z.number(), b: z.number() },
71      async ({ a, b }) => ({
72        content: [{ type: "text", text: String(a + b) }],
73      })
74    );
75 
76    // Tool that calls external API
77    this.server.tool(
78      "get_weather",
79      { city: z.string() },
80      async ({ city }) => {
81        const response = await fetch(`https://api.weather.com/${city}`);
82        const data = await response.json();
83        return {
84          content: [{ type: "text", text: JSON.stringify(data) }],
85        };
86      }
87    );
88  }
89}
90```
91 
92### Step 2: Configure Entry Point
93 
94**Public server** (`src/index.ts`):
95 
96```typescript
97import { MyMCP } from "./mcp";
98 
99export default {
100  fetch(request: Request, env: Env, ctx: ExecutionContext) {
101    const url = new URL(request.url);
102    if (url.pathname === "/mcp") {
103      return MyMCP.serveSSE("/mcp").fetch(request, env, ctx);
104    }
105    return new Response("MCP Server", { status: 200 });
106  },
107};
108 
109export { MyMCP };
110```
111 
112**Authenticated server** — See [references/oauth-setup.md](references/oauth-setup.md).
113 
114### Step 3: Test Locally
115 
116```bash
117# Start server
118npm start
119 
120# In another terminal, test with MCP Inspector
121npx @modelcontextprotocol/inspector@latest
122# Open http://localhost:5173, enter http://localhost:8788/mcp
123```
124 
125### Step 4: Deploy
126 
127```bash
128npx wrangler deploy
129```
130 
131Server accessible at `https://[worker-name].[account].workers.dev/mcp`
132 
133### Step 5: Connect Clients
134 
135**Claude Desktop** (`claude_desktop_config.json`):
136 
137```json
138{
139  "mcpServers": {
140    "my-server": {
141      "command": "npx",
142      "args": ["mcp-remote", "https://my-mcp.workers.dev/mcp"]
143    }
144  }
145}
146```
147 
148Restart Claude Desktop after updating config.
149 
150## Tool Patterns
151 
152### Return Types
153 
154```typescript
155// Text response
156return { content: [{ type: "text", text: "result" }] };
157 
158// Multiple content items
159return {
160  content: [
161    { type: "text", text: "Here's the data:" },
162    { type: "text", text: JSON.stringify(data, null, 2) },
163  ],
164};
165```
166 
167### Input Validation with Zod
168 
169```typescript
170this.server.tool(
171  "create_user",
172  {
173    email: z.string().email(),
174    name: z.string().min(1).max(100),
175    role: z.enum(["admin", "user", "guest"]),
176    age: z.number().int().min(0).optional(),
177  },
178  async (params) => {
179    // params are fully typed and validated
180  }
181);
182```
183 
184### Accessing Environment/Bindings
185 
186```typescript
187export class MyMCP extends McpAgent<Env> {
188  async init() {
189    this.server.tool("query_db", { sql: z.string() }, async ({ sql }) => {
190      // Access D1 binding
191      const result = await this.env.DB.prepare(sql).all();
192      return { content: [{ type: "text", text: JSON.stringify(result) }] };
193    });
194  }
195}
196```
197 
198## Authentication
199 
200For OAuth-protected servers, see [references/oauth-setup.md](references/oauth-setup.md).
201 
202Supported providers:
203- GitHub
204- Google
205- Auth0
206- Stytch
207- WorkOS
208- Any OAuth 2.0 compliant provider
209 
210## Wrangler Configuration
211 
212Minimal `wrangler.toml`:
213 
214```toml
215name = "my-mcp-server"
216main = "src/index.ts"
217compatibility_date = "2024-12-01"
218 
219[durable_objects]
220bindings = [{ name = "MCP", class_name = "MyMCP" }]
221 
222[[migrations]]
223tag = "v1"
224new_classes = ["MyMCP"]
225```
226 
227With bindings (D1, KV, etc.):
228 
229```toml
230[[d1_databases]]
231binding = "DB"
232database_name = "my-db"
233database_id = "xxx"
234 
235[[kv_namespaces]]
236binding = "KV"
237id = "xxx"
238```
239 
240## Common Issues
241 
242### "Tool not found" in Client
243 
2441. Verify tool name matches exactly (case-sensitive)
2452. Ensure `init()` registers tools before connections
2463. Check server logs: `wrangler tail`
247 
248### Connection Fails
249 
2501. Confirm endpoint path is `/mcp`
2512. Check CORS if browser-based client
2523. Verify Worker is deployed: `wrangler deployments list`
253 
254### OAuth Redirect Errors
255 
2561. Callback URL must match OAuth app config exactly
2572. Check `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are set
2583. For local dev, use `http://localhost:8788/callback`
259 
260## References
261 
262- [references/examples.md](references/examples.md) — Official templates and production examples
263- [references/oauth-setup.md](references/oauth-setup.md) — OAuth provider configuration
264- [references/tool-patterns.md](references/tool-patterns.md) — Advanced tool examples
265- [references/troubleshooting.md](references/troubleshooting.md) — Error codes and fixes
266