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, and importing the package (any subpath) never reads it, so a bad framework variable surfaces when createApp() starts: the Configuration error — server failed to start banner lists each failure as the variable, its schema path, and the reason ( - CANVAS_DEFAULT_ROW_LIMIT (canvas.defaultRowLimit): Too small: expected number to be >=1), and the process exits 1. The thrown ConfigurationError carries the same failures as data.issues ({ envVar, path, message, code }). createWorkerHandler() drops any config cached before its first request and re-parses after the bindings are injected.

Startup overrides must survive reparsing. createApp() resets core config when applying identity or session-mode options, so an earlier resetConfig(overrides) is not a persistent application default. After dotenv loading, seed server defaults into unset environment variables (including blank or whole-value placeholder settings), preserve explicit operator values, then reset the cached config. Validate the resolved core.config in setup().

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 a node_modules tree and the process runs from the directory owning that tree — a test runner is the usual case — the nearest manifest at or above the working directory wins instead. That also covers a workspace monorepo, where the runner is hoisted to the repo root while the process runs from a package directory: an owner that is a strict ancestor of the working directory qualifies only when it declares a workspace (a workspaces field in its manifest, or a pnpm-workspace.yaml beside it), which is what keeps a cache prefix or a plain project root — equally ancestors of a working directory inside them — from overriding an installed package's own identity. The owner is the outermost node_modules boundary, so a transitively-installed runner and a pnpm isolated layout resolve the same way. With no manifest reachable, the framework's own identity is the fallback.