api-config

name	api-config
description	Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
metadata	{"author":"cyanheads","version":"1.1","audience":"external","type":"reference"}

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 overrides passed to createApp() or createWorkerHandler()
2. Environment variables
3. package.json fields

---

Identity

Env Var	AppConfig field	Default	Notes
MCP_SERVER_NAME	mcpServerName	package.json name	Overrides package name
MCP_SERVER_VERSION	mcpServerVersion	package.json version	Overrides package version
MCP_SERVER_DESCRIPTION	mcpServerDescription	package.json description	Optional
PACKAGE_NAME	pkg.name	package.json name	Rarely needed
PACKAGE_VERSION	pkg.version	package.json version	Rarely needed
NODE_ENV	environment	development	Aliases: dev→development, prod→production, test→testing
MCP_LOG_LEVEL	logLevel	debug	Aliases: warn→warning, err→error, fatal/silent→emerg, trace→debug, information→info
LOGS_DIR	logsPath	<project-root>/logs	Node.js only; absolute or relative to project root

---

Transport

Env Var	AppConfig field	Default	Notes
MCP_TRANSPORT_TYPE	mcpTransportType	stdio	stdio | http
MCP_HTTP_PORT	mcpHttpPort	3010	Port for HTTP transport
MCP_HTTP_HOST	mcpHttpHost	127.0.0.1	Bind address
MCP_HTTP_ENDPOINT_PATH	mcpHttpEndpointPath	/mcp	HTTP endpoint path
MCP_HTTP_MAX_PORT_RETRIES	mcpHttpMaxPortRetries	15	Retry count if port is busy
MCP_HTTP_PORT_RETRY_DELAY_MS	mcpHttpPortRetryDelayMs	50	Delay between port retries (ms)
MCP_SESSION_MODE	mcpSessionMode	auto	stateless | stateful | auto
MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS	mcpStatefulSessionStaleTimeoutMs	1800000	30 min; stale session eviction
MCP_RESPONSE_VERBOSITY	mcpResponseVerbosity	standard	minimal | standard | full
MCP_ALLOWED_ORIGINS	mcpAllowedOrigins	—	Comma-separated list; omit to allow all
MCP_SERVER_RESOURCE_IDENTIFIER	mcpServerResourceIdentifier	—	RFC 8707 resource indicator URL

---

Auth

Env Var	AppConfig field	Default	Notes
MCP_AUTH_MODE	mcpAuthMode	none	none | jwt | oauth
MCP_AUTH_SECRET_KEY	mcpAuthSecretKey	—	Required for jwt mode; min 32 chars
OAUTH_ISSUER_URL	oauthIssuerUrl	—	Required for oauth mode
OAUTH_AUDIENCE	oauthAudience	—	Required for oauth mode
OAUTH_JWKS_URI	oauthJwksUri	—	Override JWKS endpoint (otherwise derived from issuer)
OAUTH_JWKS_COOLDOWN_MS	oauthJwksCooldownMs	300000	5 min; min time between JWKS refetches
OAUTH_JWKS_TIMEOUT_MS	oauthJwksTimeoutMs	5000	JWKS fetch timeout (ms)
DEV_MCP_AUTH_BYPASS	devMcpAuthBypass	false	Skip auth in development; blocked in production
DEV_MCP_CLIENT_ID	devMcpClientId	—	Dev-only: override client ID
DEV_MCP_SCOPES	devMcpScopes	—	Dev-only: comma-separated scope overrides

OAuth proxy (optional sub-object)

Activated when OAUTH_PROXY_AUTHORIZATION_URL or OAUTH_PROXY_TOKEN_URL is set.

Env Var	AppConfig field	Notes
OAUTH_PROXY_AUTHORIZATION_URL	oauthProxy.authorizationUrl	Proxy authorization endpoint
OAUTH_PROXY_TOKEN_URL	oauthProxy.tokenUrl	Proxy token endpoint
OAUTH_PROXY_REVOCATION_URL	oauthProxy.revocationUrl	Optional
OAUTH_PROXY_ISSUER_URL	oauthProxy.issuerUrl	Optional
OAUTH_PROXY_SERVICE_DOCUMENTATION_URL	oauthProxy.serviceDocumentationUrl	Optional
OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS	oauthProxy.defaultClientRedirectUris	Comma-separated list

---

Storage

Env Var	AppConfig field	Default	Notes
STORAGE_PROVIDER_TYPE	storage.providerType	in-memory	in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1; aliases: mem, fs
STORAGE_FILESYSTEM_PATH	storage.filesystemPath	./.storage	Used only when providerType is filesystem

Supabase (optional sub-object)

Activated when both SUPABASE_URL and SUPABASE_ANON_KEY are set.

Env Var	AppConfig field	Notes
SUPABASE_URL	supabase.url	Required to activate
SUPABASE_ANON_KEY	supabase.anonKey	Required to activate
SUPABASE_SERVICE_ROLE_KEY	supabase.serviceRoleKey	Optional; elevated access

---

LLM

Env Var	AppConfig field	Default	Notes
OPENROUTER_API_KEY	openrouterApiKey	—	Optional; enables LLM provider
OPENROUTER_APP_URL	openrouterAppUrl	http://localhost:3000	Reported to OpenRouter
OPENROUTER_APP_NAME	openrouterAppName	package.json name	Reported to OpenRouter
LLM_DEFAULT_MODEL	llmDefaultModel	google/gemini-2.5-flash-preview-05-20	OpenRouter model ID
LLM_DEFAULT_TEMPERATURE	llmDefaultTemperature	—	Float
LLM_DEFAULT_TOP_P	llmDefaultTopP	—	Float
LLM_DEFAULT_MAX_TOKENS	llmDefaultMaxTokens	—	Integer
LLM_DEFAULT_TOP_K	llmDefaultTopK	—	Integer
LLM_DEFAULT_MIN_P	llmDefaultMinP	—	Float

---

Telemetry

Env Var	AppConfig field	Default	Notes
OTEL_ENABLED	openTelemetry.enabled	false	Enable OpenTelemetry export
OTEL_SERVICE_NAME	openTelemetry.serviceName	package.json name
OTEL_SERVICE_VERSION	openTelemetry.serviceVersion	package.json version
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	openTelemetry.tracesEndpoint	—	OTLP traces endpoint URL
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	openTelemetry.metricsEndpoint	—	OTLP metrics endpoint URL
OTEL_TRACES_SAMPLER_ARG	openTelemetry.samplingRatio	1.0	0–1; fraction of traces to export
OTEL_LOG_LEVEL	openTelemetry.logLevel	INFO	OTel SDK internal log level: NONE | ERROR | WARN | INFO | DEBUG | VERBOSE | ALL

---

Tasks

Env Var	AppConfig field	Default	Notes
TASK_STORE_TYPE	tasks.storeType	in-memory	in-memory | storage; aliases: mem/memory→in-memory, persistent→storage
TASK_STORE_TENANT_ID	tasks.tenantId	system-tasks	Tenant ID for task state storage
TASK_STORE_DEFAULT_TTL_MS	tasks.defaultTtlMs	—	TTL for completed tasks (ms); null = no expiry

---

Speech (optional sub-object)

Activated when SPEECH_TTS_ENABLED or SPEECH_STT_ENABLED is set.

TTS (Text-to-Speech)

Env Var	AppConfig field	Default	Notes
SPEECH_TTS_ENABLED	speech.tts.enabled	false	Enable TTS
SPEECH_TTS_PROVIDER	speech.tts.provider	elevenlabs	Currently only elevenlabs
SPEECH_TTS_API_KEY	speech.tts.apiKey	—	Provider API key
SPEECH_TTS_BASE_URL	speech.tts.baseUrl	—	Override provider base URL
SPEECH_TTS_DEFAULT_VOICE_ID	speech.tts.defaultVoiceId	—	Default voice identifier
SPEECH_TTS_DEFAULT_MODEL_ID	speech.tts.defaultModelId	—	Default model identifier
SPEECH_TTS_TIMEOUT	speech.tts.timeout	—	Request timeout (ms)

STT (Speech-to-Text)

Env Var	AppConfig field	Default	Notes
SPEECH_STT_ENABLED	speech.stt.enabled	false	Enable STT
SPEECH_STT_PROVIDER	speech.stt.provider	openai-whisper	Currently only openai-whisper
SPEECH_STT_API_KEY	speech.stt.apiKey	—	Provider API key
SPEECH_STT_BASE_URL	speech.stt.baseUrl	—	Override provider base URL
SPEECH_STT_DEFAULT_MODEL_ID	speech.stt.defaultModelId	—	Default model identifier
SPEECH_STT_TIMEOUT	speech.stt.timeout	—	Request timeout (ms)

---

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';

const ServerConfigSchema = z.object({
  myApiKey: z.string().describe('External API key'),
  maxResults: z.coerce.number().default(100),
});

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

let _config: ServerConfig | undefined;

export function getServerConfig(): ServerConfig {
  _config ??= ServerConfigSchema.parse({
    myApiKey: process.env.MY_API_KEY,
    maxResults: process.env.MY_MAX_RESULTS,
  });
  return _config;
}

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.