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 { allToolDefinitions } from './mcp-server/tools/index.js';
import { allResourceDefinitions } from './mcp-server/resources/index.js';
import { allPromptDefinitions } from './mcp-server/prompts/index.js';
import { initMyService } from './services/my-domain/my-service.js';

export default createWorkerHandler({
  tools: allToolDefinitions,
  resources: allResourceDefinitions,
  prompts: allPromptDefinitions,
  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
  },
});

Options

Option	Type	Purpose
tools	AnyToolDefinition[]	Tool definitions to register
resources	AnyResourceDefinition[]	Resource definitions to register
prompts	PromptDefinition[]	Prompt definitions to register
setup	(core: CoreServices) => void | Promise<void>	Runs after core services are ready, during the first request (lazy init inside the fetch handler)
extraEnvBindings	[bindingKey: string, processEnvKey: string][]	Maps CF string bindings to process.env keys
extraObjectBindings	[bindingKey: string, globalKey: string][]	Maps CF object bindings (KV, R2, D1, AI) to globalThis keys
onScheduled	(controller, env, ctx) => Promise<void>	Cloudflare cron trigger handler

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.