Route /mcp through a Durable Object for session persistence

Effect's McpServer holds sessions in memory; Workers are stateless across
requests, so initialize and tools/call landed in different isolates (404).
Route all /mcp traffic to one singleton Durable Object so the session map
persists across requests — the CF-native way to run MCP-over-HTTP.

Author: RhysSullivan

worker/index.ts

@@ -1,9 +1,19 @@
 import { detect } from "../src/lib/detect.ts";
-import { mcpHandler } from "./registry.ts";
+
+export { McpDurableObject } from "./mcp-do.ts";
+
+interface DurableObjectStub {
+  fetch: (request: Request) => Promise<Response>;
+}
+interface DurableObjectNamespace {
+  idFromName: (name: string) => unknown;
+  get: (id: unknown) => DurableObjectStub;
+}
 
 export interface Env {
   ASSETS: { fetch: (request: Request) => Promise<Response> };
   POSTHOG_KEY: string;
+  MCP: DurableObjectNamespace;
 }
 
 const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
@@ -28,8 +38,10 @@ export default {
     const url = new URL(request.url);
 
     // MCP server (write-once tool registry) — point Claude/Cursor at /mcp.
+    // Routed through a single Durable Object so the session map persists.
     if (url.pathname === "/mcp") {
-      return mcpHandler(request);
+      const stub = env.MCP.get(env.MCP.idFromName("mcp"));
+      return stub.fetch(request);
     }
 
     // Detection endpoint: run the full agent-readiness battery for a domain.

worker/mcp-do.ts

@@ -0,0 +1,18 @@
+/**
+ * Durable Object that hosts the MCP server.
+ *
+ * Effect's McpServer keeps client sessions in an in-memory Map (created on
+ * `initialize`, required by `tools/call`). Plain Workers are stateless across
+ * requests, so the session is lost between calls. A Durable Object is a single
+ * persistent instance — routing all /mcp traffic to one DO keeps the session
+ * map alive across requests, which is how MCP-over-HTTP works on Cloudflare.
+ */
+import { mcpHandler } from "./registry.ts";
+
+export class McpDurableObject {
+  constructor(_state: unknown, _env: unknown) {}
+
+  fetch(request: Request): Promise<Response> {
+    return mcpHandler(request);
+  }
+}

wrangler.jsonc

@@ -17,5 +17,9 @@
   ],
   "observability": {
     "enabled": true
-  }
+  },
+  "durable_objects": {
+    "bindings": [{ "name": "MCP", "class_name": "McpDurableObject" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["McpDurableObject"] }]
 }