API Config

Overview

Configuration has two layers: core config (managed by the framework, env-driven) and server config (your own Zod schema for domain-specific env vars). Never merge them.

Import: AppConfig, config, parseConfig, resetConfig, ConfigSchema from @cyanheads/mcp-ts-core/config.

Core config

Managed by @cyanheads/mcp-ts-core. Validated via Zod from environment variables. Uses a lazy proxy — parsing is deferred until the first property read.

Priority (highest to lowest):

1. name/version/title/websiteUrl/description/icons options passed to createApp() or createWorkerHandler()
2. Environment variables
3. sessionMode.default passed to createApp() — a default, so it sits below the env var it seeds, unlike the identity options above
4. package.json fields

Where package.json is read from: the application root — the nearest package.json at or above the process entry module (process.argv[1]), which is the served package on every launch path (npx, .mcpb, a client config naming dist/index.js), none of which run from the package root. The launching client's working directory is never the anchor: a stdio client starts the server from wherever it happens to be, so reading identity from there makes a server report a foreign project's name and version. When the entry module is a tool installed under the project's own node_modules and the process runs from that project — a test runner is the usual case — the project's manifest wins. With no manifest reachable, the framework's own identity is the fallback.

Identity

SDK identity fields (API-only, no env var equivalent — passed to createApp() / createWorkerHandler(), forwarded to initialize and /.well-known/mcp.json):

Cache hints (cacheHints)

API-only, no env var. Sets the ttlMs / cacheScope a client may cache a cacheable result for on protocol revision 2026-07-28. Keys are the closed set of cacheable operations: tools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover.

await createApp({
  cacheHints: {
    'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
    'resources/read': { ttlMs: 60_000 },
  },
});

• ttlMs — cache lifetime in milliseconds; must be a non-negative safe integer. An invalid value fails at startup with a ConfigurationError naming the field.
• cacheScope — 'private' (only the requesting client may cache) or 'public' (shared caches may too).
• A resource's own cacheHint overrides the resources/read entry for that resource, field by field — see the add-resource skill.
• Omitting a hint keeps the SDK defaults (ttlMs: 0, cacheScope: 'private'). Responses to 2025-era clients are never affected.

Session mode (sessionMode)

Declares the session posture in src/ instead of leaving it to a deployment's MCP_SESSION_MODE. The bare string is shorthand for { default }. HTTP only — MCP_SESSION_MODE has no effect on stdio.

await createApp({ sessionMode: 'stateless' });                                  // default only
await createApp({ sessionMode: { default: 'stateful', require: 'stateful' } }); // and enforced

• default applies only when MCP_SESSION_MODE carries no meaningful value. An empty string and a whole-value unsubstituted ${…} placeholder both read as unset on the config path, so both fall through to the option rather than to the schema default (auto). An explicit MCP_SESSION_MODE always wins.
• require: 'stateful' fails startup with a ConfigurationError naming the conflicting env value when the resolved HTTP mode is stateless, before any service is constructed. Declare it when a handler gates a destructive action behind ctx.requestInput / inputRequired.elicit — see the MCP_SESSION_MODE row for why that combination is unusable for 2025-era clients. There is no require: 'stateless'; nothing needs statelessness to work.
• The advertised transport.sessionMode follows automatically — resolveSessionMode is the single resolution the manifest, the session store, and the ctx.sessionId gate all read — and still never publishes auto.
• Cloudflare Workers are outside this contract: MCP_SESSION_MODE is not in CORE_ENV_BINDINGS, so a [vars] entry reaches process.env only through extraEnvBindings.

Environment & logging

Transport

Port binding

MCP_HTTP_PORT is where the HTTP transport starts, not necessarily where it ends up. Startup walks a ladder: bind MCP_HTTP_PORT, and on a collision wait MCP_HTTP_PORT_RETRY_DELAY_MS and try the next port, up to MCP_HTTP_MAX_PORT_RETRIES times. Read the bound port off the HTTP transport listening at … log line or the startup banner — with the defaults the server may be anywhere in 3010–3025. Pin the port by setting MCP_HTTP_MAX_PORT_RETRIES=0, which makes a collision a startup failure instead of a silent move.

• Startup resolves only once the server reports 'listening'. A bind failure arriving after the listen call — a collision the pre-bind probe could not see, because another process took the port in between — is routed to the ladder like any other, not reported as a successful start.
• A failure the ladder cannot clear rejects immediately. Each rung only changes the port, so EACCES (privileged port, typically <1024 as a non-root user) and EADDRNOTAVAIL (the MCP_HTTP_HOST address is not local to this machine) fail startup on the first attempt with the OS error as the rejection's cause, rather than burning every rung. Ladder exhaustion carries the last bind error as cause too, when a real bind attempt produced one.
• Runtime caveat: Bun reports a permission-denied bind as EADDRINUSE where Node reports EACCES. On Bun a privileged port therefore reads as an ordinary collision and walks the whole ladder before failing with Failed to bind to any port after N retries. — on Node the same port fails on the first attempt, naming EACCES.

Auth

Storage

Canvas (DataCanvas primitive — Tier 3, optional peer dep @duckdb/node-api)

Platform support: Linux/macOS/Windows × x64 supported, Linux/macOS arm64 supported. Windows arm64 unsupported (DuckDB upstream). See api-canvas skill for the full DataCanvas reference.

Supabase (optional sub-object)

Activated when SUPABASE_URL is set.

LLM

Telemetry

Speech (optional sub-object)

Activated when SPEECH_TTS_ENABLED or SPEECH_STT_ENABLED is set.

TTS (Text-to-Speech)

STT (Speech-to-Text)

Server config (separate schema)

Define your own Zod schema for domain-specific env vars. Never merge with core's schema.

Use the lazy init/accessor pattern — do not parse process.env at module top-level.

// src/config/server-config.ts
import { z } from '@cyanheads/mcp-ts-core';
import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';

const ServerConfigSchema = z.object({
  apiKey: z.string().describe('External API key'),
  maxResults: z.coerce.number().default(100),
  verboseLogging: z.stringbool().default(false).describe('Enable verbose logging'),
});

export type ServerConfig = z.infer<typeof ServerConfigSchema>;

let _config: ServerConfig | undefined;

export function getServerConfig(): ServerConfig {
  _config ??= parseEnvConfig(ServerConfigSchema, {
    apiKey: 'MY_API_KEY',
    maxResults: 'MY_MAX_RESULTS',
    verboseLogging: 'MY_VERBOSE_LOGGING',
  });
  return _config;
}

Env booleans — use z.stringbool(), never z.coerce.boolean(). z.coerce.boolean() runs Boolean(value), so "false", "0", and "no" all coerce to true — the flag becomes impossible to disable through the environment except by omitting it entirely. z.stringbool() parses true/false/1/0/yes/no/on/off (case-insensitive) and rejects anything else, so MY_VERBOSE_LOGGING=false actually disables and a typo fails loudly at startup instead of silently coercing. Empty string and unset both fall through to .default().

Unset means unset. parseEnvConfig and the framework's own config both treat an empty string and a whole-value ${…} placeholder — what an MCPB or plugin host forwards when a user leaves an option blank and nothing substitutes it — as the variable being absent: an optional field stays undefined, a defaulted field takes its default, and a required field fails as missing rather than as a format error against the literal text. A value that merely contains ${…} is kept. No per-field z.preprocess guard is needed for either case.

Why parseEnvConfig? It maps Zod schema paths to env var names so validation errors name the actual variable at fault. A missing MY_API_KEY produces:

Server config validation failed:
  - MY_API_KEY (apiKey): Invalid input: expected string, received undefined

Instead of a raw ZodError dump at startup. The framework catches the resulting ConfigurationError and prints a clean banner (full stack behind DEBUG=true).

Direct ServerConfigSchema.parse(...) still works — the framework intercepts raw ZodError thrown from setup() and converts it — but error messages won't know about env var names, so they show the Zod path (apiKey) instead of the variable name (MY_API_KEY).

Workers: Do not parse process.env at module top-level. In Workers, env bindings are injected at request time via injectEnvVars(), after all static imports. Lazy parsing is required.