api-workers

Overview

@cyanheads/mcp-ts-core/worker exports createWorkerHandler — the Workers entry point. It wraps tool/resource/prompt registries into a per-request McpServer factory that integrates with the Cloudflare Workers runtime.

createWorkerHandler(options)

import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
import { echoTool } from './mcp-server/tools/definitions/echo.tool.js';
import { echoResource } from './mcp-server/resources/definitions/echo.resource.js';
import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
import { initMyService } from './services/my-domain/my-service.js';

export default createWorkerHandler({
  tools: [echoTool],
  resources: [echoResource],
  prompts: [echoPrompt],
  setup(core) {
    initMyService(core.config, core.storage);
  },
  extraEnvBindings: [['MY_API_KEY', 'MY_API_KEY']],
  extraObjectBindings: [['MY_CUSTOM_KV', 'MY_CUSTOM_KV']],
  onScheduled: async (controller, env, ctx) => {
    // Cloudflare cron trigger handler
  },
});

Fresh scaffolds register definitions directly in the entry point as shown above. If your project later adds barrel files for definitions, importing arrays from those barrels is also fine.

Options

Key design points

• Per-request McpServer factory: a new server instance is created for each request. Required by SDK security advisory GHSA-345p-7cg4-v4c7.
• Env bindings refreshed per-request: Cloudflare may rotate binding object references between requests; the handler re-injects them on every call.
• ctx.waitUntil() is documented but not yet called by the framework: the ExecutionContext is received and passed through to app.fetch and onScheduled, but the framework does not currently call ctx.waitUntil() for telemetry flush. Spans complete synchronously within the request lifecycle.
• Singleton app promise with retry-on-failure: the framework init runs once; if it fails, the next request retries rather than leaving the Worker in a permanently broken state.

Binding types

Cloudflare Workers bindings come in two kinds with different injection mechanisms:

extraEnvBindings: array of [bindingKey, processEnvKey] tuples. The value of env[bindingKey] is assigned to process.env[processEnvKey] at request time.

extraObjectBindings: array of [bindingKey, globalKey] tuples. The object at env[bindingKey] is stored on globalThis[globalKey] at request time.

Both are refreshed on every request. Never cache binding references between requests.

CloudflareBindings extensibility

Core defines CloudflareBindings without an index signature, so servers extend it via intersection rather than module augmentation:

import type { CloudflareBindings as CoreBindings } from '@cyanheads/mcp-ts-core/worker';

interface MyBindings extends CoreBindings {
  MY_CUSTOM_KV: KVNamespace;
  MY_R2_BUCKET: R2Bucket;
}

Pass MyBindings as a type parameter where the framework accepts a generic env type (e.g., Hono route handlers, onScheduled).

Runtime compatibility

runtimeCaps feature detection

import { runtimeCaps } from '@cyanheads/mcp-ts-core/utils';

if (runtimeCaps.isWorkerLike) {
  // Workers-specific path
}

if (runtimeCaps.isNode) {
  // Node.js-specific path (e.g., filesystem access)
}

runtimeCaps is a snapshot taken at import time. Fields: isNode, isBun, isWorkerLike, isBrowserLike, hasProcess, hasBuffer, hasTextEncoder, hasPerformanceNow. All booleans, never throw.

Serverless storage whitelist

In Workers, only these storage providers are allowed:

filesystem and supabase are not on the whitelist and behave differently:

• filesystem and other unknown types are silently forced to in-memory (a warning is logged) in a serverless environment.
• supabase does not silently fall back. The framework attempts to connect and throws ConfigurationError if credentials (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) are missing or the client cannot be constructed. Do not set STORAGE_PROVIDER_TYPE=supabase in a Worker.

Set STORAGE_PROVIDER_TYPE to one of the four whitelisted values to avoid unexpected behavior.

wrangler.toml requirements

compatibility_flags = ["nodejs_compat"]
compatibility_date = "2025-09-01"  # must be >= 2025-09-01

[[kv_namespaces]]
binding = "MY_CUSTOM_KV"
id = "..."

[[r2_buckets]]
binding = "MY_R2_BUCKET"
bucket_name = "..."

nodejs_compat is required for Node.js API shims (e.g., process.env, Buffer, crypto). The minimum compatibility_date activates the required shim set.

Workers-specific warnings

Lazy env parsing is mandatory. Cloudflare injects env bindings at request time via injectEnvVars(), after all static module imports complete. Never parse process.env at module top-level in Workers:

// WRONG — parsed before env is injected
const apiKey = process.env.MY_API_KEY;  // undefined in Workers

// CORRECT — lazy parse inside a function or getter
export function getServerConfig() {
  return ServerConfigSchema.parse({ apiKey: process.env.MY_API_KEY });
}

in-memory storage is volatile. Data stored with the in-memory provider is lost between cold starts and is not shared across Worker instances. Use cloudflare-kv, cloudflare-r2, or cloudflare-d1 for any state that must persist or be shared.

Node-only utilities throw in Workers. scheduler (node-cron), sanitizePath (fs-based), and filesystem storage provider all throw ConfigurationError when called from a Worker. Guard with runtimeCaps.isNode or avoid entirely.