Cloudflare Worker

​

Path 1 — Deploy a FrontMCP app (decorator build)

// src/main.ts
import 'reflect-metadata';
import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';

@Tool({ name: 'echo', description: 'Echo a message', inputSchema: { message: z.string() } })
class EchoTool extends ToolContext {
async execute(input: { message: string }) {
return { content: [{ type: 'text' as const, text: `Echo: ${input.message}` }] };
}
}

@App({ id: 'demo', name: 'demo', tools: [EchoTool] })
class DemoApp {}

@FrontMcp({
info: { name: 'my-worker', version: '1.0.0' },
apps: [DemoApp],
// Serve MCP at /mcp (the worker default is root `/`). See "Endpoint path,
// CORS & SSE" below — all three are driven by this same `http`/`transport` config.
// You can also declare it once as `transport.http.path` in frontmcp.config;
// the cloudflare build feeds that in as this field's default.
http: { entryPath: '/mcp' },
})
class MyServer {}

export default MyServer;

// frontmcp.config.js
module.exports = {
  name: 'my-worker',
  entry: './src/main.ts',
  deployments: [{ target: 'cloudflare', wrangler: { name: 'my-worker' } }],
};

frontmcp build --target cloudflare

name = "my-worker"
main = "dist/cloudflare/index.js"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat", "nodejs_compat_populate_process_env"]

npx wrangler dev            # boots the bundle in workerd (same engine as prod)
npx wrangler login          # one-time auth to your account
npx wrangler deploy

curl https://my-worker.<subdomain>.workers.dev/healthz
# → { "status": "ok", "transport": "web-fetch", "server": { "name": "my-worker", ... } }

curl -s https://my-worker.<subdomain>.workers.dev/mcp \
 -H 'content-type: application/json' \
 -H 'accept: application/json, text/event-stream' \
 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

​

Secrets, vars and process.env

const sid = process.env.TWILIO_ACCOUNT_SID; // set via `wrangler secret put`

@Tool({ name: 'cache_get' })
class CacheGet extends ToolContext {
  async execute({ key }: { key: string }) {
    const kv = this.workerEnv?.MY_KV as KVNamespace | undefined; // undefined outside a Worker request
    return kv?.get(key);
  }
}

​

Required secrets

npx wrangler secret put MCP_SESSION_SECRET   # openssl rand -hex 32

# Only when auth.mode is `local` or `remote`; `public` and `transparent`
# never mint local JWTs and do not read this.
npx wrangler secret put JWT_SECRET           # openssl rand -hex 32

​

When the server fails to start

​

Background tasks

​

Startup checks

​

Endpoint path, CORS & SSE — all config-driven

export default createEdgeMcp({
  info: { name: 'my-worker', version: '1.0.0' },
  apps: [MyApp],
  tasks: { enabled: false },
  http: {
    entryPath: '/mcp',        // the ONE path MCP is served at (omit → root '/')
    cors: { origin: true },   // reflect Origin so a browser MCP client (Inspector "Direct") can connect
  },
  // transport: 'legacy' (default) / 'modern' → SSE streaming on POST;
  // transport: 'stateless-api' → buffered JSON responses instead.
});

• CORS comes from http.cors (false to disable, { origin, credentials, maxAge } to configure). A function origin isn’t supported on the worker — use a static origin (true / string / string[]).
• SSE is derived from the transport protocol: streaming is on when Streamable HTTP is enabled and JSON-buffering is off (true under legacy/modern, false under stateless-api). Server→client GET streams are always honored.
• A trailing slash is normalized (/mcp/ matches /mcp); /healthz + /readyz always answer a liveness 200 regardless of entryPath.

The decorator-build path (@FrontMcp({ http, transport }) + frontmcp build --target cloudflare) and the @frontmcp/edge createEdgeMcp({ http, transport }) path read the same config, so the endpoint path / CORS / SSE behave identically on both.

​

Path 2 — Managed auto-updating edge (@frontmcp/edge)

// worker.ts
import { env } from 'cloudflare:workers';
import { createEdgeMcp, kvBundleCacheFromEnv } from '@frontmcp/edge';

export default createEdgeMcp({
  info: { name: 'my-worker', version: '1.0.0' },
  apps: [],
  tasks: { enabled: false },
  managed: {
    endpoint: 'https://cloud.example.com/v1/bundles/acme',
    // The pull JWT the SaaS issued for this server (iss = expectedIssuer, aud includes
    // expectedAudience, with exp), kept in a Worker secret:
    //   npx wrangler secret put FRONTMCP_PULL_TOKEN
    authToken: env.FRONTMCP_PULL_TOKEN,
    expectedAudience: 'acme-mcp',
    jwksUrl: 'https://cloud.example.com/.well-known/jwks.json',
    expectedIssuer: 'https://cloud.example.com',
    // KV-backed last-good cache, resolved from the per-request `env` (CF bindings
    // live on `env`, not module scope — so pass the factory, not a built store).
    cache: kvBundleCacheFromEnv('BUNDLE_CACHE'),
  },
});

​

Required wrangler.toml (hand-maintained)

name = "my-worker"
main = "worker.ts"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]

# Last-good bundle cache (createEdgeMcp reads it via kvBundleCacheFromEnv).
[[kv_namespaces]]
binding = "BUNDLE_CACHE"
id = "<your-kv-namespace-id>"   # create with: npx wrangler kv namespace create BUNDLE_CACHE

# Cron Trigger that drives scheduled() → refresh. Set your refresh cadence here
# (the `managed.pollIntervalMs` option is IGNORED on edge — Workers have no
# background timers between requests).
[triggers]
crontabs = ["*/5 * * * *"]

​

How the cache + refresh behave

• Boot: the first request lazily builds the scope and pulls the bundle. If the pull fails, it falls back to the last-good bundle in KV (validated against the bundle schema) so a SaaS outage doesn’t kill the server.
• Refresh: the Cron Trigger invokes scheduled(), which pulls a fresh bundle, persists it to KV, and hot-swaps the live skill/tool registries — emitting notifications/*/list_changed.
• Single-flight: boot and Cron refresh are mutually exclusive (no double-pull on cold start).
• No redirects: the pull sends authToken as a bearer token and never follows a redirect, so endpoint must serve the bundle directly; a 3xx (or a status-0 opaqueredirect) fails the pull.
• No source attached → loud failure: if the bundle source can’t be constructed, scheduled() throws so the Cron run is reported as failed rather than silently succeeding with a stale bundle.

​

Storage on the edge

import { createStorage } from '@frontmcp/utils';

const storage = await createStorage({
  type: 'cloudflare-kv',
  cloudflareKv: { namespace: env.MY_KV },  // a KV binding from the Worker env
});

• Atomic counters (incr/decr/incrBy) — no atomic increment on KV.
• Conditional writes (ifNotExists/ifExists) — no compare-and-set.
• TTL introspection (ttl) — KV doesn’t expose remaining TTL.

​

Stateful sessions & notifications (Durable Objects)

// worker.ts
const mcp = createEdgeMcp({
  info: { name: 'my-worker', version: '1.0.0' },
  apps: [MyApp],
  tasks: { enabled: false },
  http: { entryPath: '/mcp' },
  sessions: {}, // default binding name: FRONTMCP_SESSIONS
});
export default mcp;
export const FrontMcpSession = mcp.SessionDurableObject; // bind in wrangler.toml

# wrangler.toml
[[durable_objects.bindings]]
name = "FRONTMCP_SESSIONS"
class_name = "FrontMcpSession"

[[migrations]]
tag = "v1"
new_classes = ["FrontMcpSession"]

[vars]
MCP_SESSION_SECRET = "..." # or `wrangler secret put MCP_SESSION_SECRET`

​

Low-level: createWebFetchHandler() (custom runtimes — Deno, Bun, custom workers)

import { createWebFetchHandler } from '@frontmcp/sdk';

// `scope` comes from a booted FrontMcpInstance (e.g. instance.getScopes()[0]).
const handler = createWebFetchHandler(scope, { entryPath: '/mcp' });

// Cloudflare Worker / Deno / Bun all speak Web `Request`/`Response`:
export default { fetch: (request: Request) => handler(request) };

// Deno and Bun: forward the runtime's second argument — it is how the handler learns the client IP.
Deno.serve((request, info) => handler(request, info));
Bun.serve({ fetch: (request, server) => handler(request, server) });

​

Types

type WebFetchHandler = (request: Request) => Promise<Response>;

function createWebFetchHandler(scope: Scope, options?: CreateWebFetchHandlerOptions): WebFetchHandler;

interface CreateWebFetchHandlerOptions {
  /** MCP endpoint path(s). Defaults to the scope's `http.entryPath`, else `/`. A trailing slash is normalized; an array opts into a multi-path allow-list. */
  entryPath?: string | string[];
  /** Paths answered with a 200 liveness/readiness response. Defaults to `/healthz`, `/readyz`. */
  healthPaths?: string[];
  /** CORS for browser MCP clients. Defaults to the scope's `http.cors`. */
  cors?: WebFetchCorsOptions;
  /** Optional Durable-Object session router (stateful sessions); falls through to stateless when it returns no `Response`. */
  sessionRouter?: WebFetchSessionRouter;
}

​

Current status & limitations

• The decorator build path (frontmcp build --target cloudflare) boots on real workerd and serves MCP over /mcp with a /healthz liveness probe.
• createEdgeMcp also deploys + serves on real Cloudflare — bundled with esbuild + a small set of stubs (see the next bullet). Verified end-to-end (initialize / tools/list / tools/call). The KV last-good cache + the Cron scheduled refresh wiring are unit/integration-tested.
• The worker runs the real http:request flow — the same hookable pipeline every transport runs: session:verify (auth), router, audit, metrics + plugin/user hooks all execute on the worker. The MCP response is produced by the SDK’s web-standard Streamable HTTP transport (WebStandardStreamableHTTPServerTransport) — which is the standard transport (the Node StreamableHTTPServerTransport is a thin req/res wrapper over it). Configure transparent auth and the flow’s checkAuthorization stage returns 401 + WWW-Authenticate on the worker, just like Node.
• Stateful sessions via a Durable Object (sessions: {} + the bound SessionDurableObject): the Streamable HTTP standalone GET notification stream stays open across requests and requests for a session route back to the same DO — so server→client notifications work. Verified live.
• OAuth sign-in endpoints, including a federated provider’s redirect to /oauth/provider/:providerId/callback and the federated consent screen’s submission: the worker matches path parameters like Express, so remote mode and local providers finish a sign-in on the worker.
• CloudflareKvStorageAdapter (KV only, with the honest limits above).

• It must run with serve: false (now the default inside createEdgeMcp) so the scope doesn’t construct the Node Express host.
• Three Node-only transports that are statically bundled but never used on the edge must be stubbed in your bundler: express (pulls node:tty), raw-body (pulls safer-buffer, which crashes at module-eval on workerd), and cross-spawn (pulls node:child_process, via the MCP stdio client). See cloudflare-sandbox/build-edge.mjs for a working esbuild config.

• Stateless mode has no server push. Without sessions, the worker is stateless and the standalone GET notification stream can’t deliver server→client notifications (each request is a fresh isolate) — enable sessions (the Durable Object) for that.
• DO session eviction. A Durable Object is evicted when idle; an in-flight session then needs to re-initialize. WebSocket-hibernation-style persistence is a follow-up.
• KV only. No R2 (blobs) or D1 (relational) stores, and no @frontmcp/adapters/cloudflare subpath yet.
• No worker observability sink, no deploy CLI / GitHub Action / push webhook, and the declarative frontmcp.deploy.yaml manifest is schema-only (no runtime consumer yet).