Configuration files

// 1. Code: the server's options
@FrontMcp({ info, apps, http: { port: 3000 }, plugins: [ConfigPlugin.init({ schema, loadYaml: true })] })

// 2. The environment FrontMCP reads: PORT, NODE_ENV, MCP_SESSION_SECRET, …
// 3. .env, .env.local and config.yml: your settings, read by ConfigPlugin into this.config
// 4. frontmcp.config.ts: read by `frontmcp dev`, `build`, `test` and `inspector`, never by the server

Reference

Where settings come from

Which setting wins

1. An option you set in @FrontMcp wins over the environment variable that provides its default. http.port wins over PORT, http.entryPath over FRONTMCP_HTTP_ENTRY_PATH, http.security.bindAddress over FRONTMCP_BIND_ADDRESS, and http.security.dnsRebindingProtection.allowedHosts over FRONTMCP_ALLOWED_HOSTS, and each field of http.securityHeaders over the FRONTMCP_* response-header variable for it. Leave an option out to let the environment decide.
2. Some settings exist only as environment variables: the secrets, NODE_ENV, and FRONTMCP_TRUST_PROXY (throttle.ipFilter.trustProxy is accepted but never read). Set them where the process starts.
3. For your own settings, with a schema: a real environment variable wins over .env.local, which wins over .env, which wins over the YAML file, which wins over the schema's defaults. Without a schema it's different: a .env file wins over the real environment.
4. The CLI passes settings to the server as environment variables. frontmcp dev turns --port or frontmcp.config's transport.http.port into PORT, and transport.http.path into FRONTMCP_HTTP_ENTRY_PATH, so an option set in @FrontMcp still wins over both. A bundle from frontmcp build carries a deployment's server block and env the same way, as variables it sets when it starts, unless the environment already has them: see what a build carries.
5. A .env file only reaches FrontMCP's own variables if it's loaded before FrontMCP reads them. frontmcp dev and frontmcp test load .env and .env.local before the server starts. ConfigPlugin loads them when the server starts, which is after FrontMCP has read PORT: see PORT in .env is ignored.

Environment variables

Every variable FrontMCP 1.9.3 reads. The last column says how this site checked it: Ran means we saw FrontMCP behave this way; Read means we read it in FrontMCP's published code without running it. Flags marked 1/true are on only when set to 1 or true.

Starting and serving

Response headers

FrontMCP's HTTP server and createFetchHandler() add security headers to every response. X-Content-Type-Options: nosniff and X-Frame-Options: DENY are on by default, X-Powered-By is removed, and the rest are off until you set them. Each variable has an option in http.securityHeaders, which wins over it. In a variable, off, false or none turns a header off; in http.securityHeaders, false does. (Before 1.8.7 FrontMCP sent neither default header, and sent X-Powered-By: Express.)

Environment and production

Environment awareness explains the detection in full.

Secrets

Set these in every deployment. Outside production, FrontMCP makes up a stand-in and logs a warning: a key derived from the machine for sessions, and a random key per process for the others, which doesn't survive a restart or match another instance's.

Storage

Logs and metrics

Set by the CLI

frontmcp sets these for the processes it starts; you don't set them yourself. FRONTMCP_CONFIG is the exception: it tells the CLI where frontmcp.config is.

Variables you name yourself are read too: an agent's apiKey: { env: "ANTHROPIC_API_KEY" }, loader.tokenEnvVar for App.esm(), and metrics.tokenEnv.

ConfigPlugin

ConfigPlugin is a built-in plugin for your own settings. It reads them when the server starts, from .env files, an optional YAML file and the environment, checks them against a Zod schema, and gives every tool, resource, agent, job and channel this.config to read them with.

import { ConfigPlugin, FrontMcp, z } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

const settings = z.object({
  desk: z
    .object({
      webUrl: z.string().url().default("https://desk.example.com"),
      pageSize: z.coerce.number().default(20),
    })
    .prefault({}),
});

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  plugins: [ConfigPlugin.init({ schema: settings, loadYaml: true })],
})
export default class Server {}

Put it in @FrontMcp({ plugins }) for every app, or in one @App({ plugins }). ConfigPlugin.init() without an argument uses the defaults (before 1.8.6 it failed with Cannot read properties of undefined (reading 'providers'), so init({}) was needed), and since 1.9.4 so does the bare ConfigPlugin class, which before registered nothing.

ConfigPlugin.init(options)

With a schema

FrontMCP starts from an empty object and fills it, each source over the one before:

1. The YAML file, when loadYaml is true. Its numbers, booleans and lists keep their types.
2. .env, then .env.local, then the real environment. Only variables whose name matches a path in the schema are used.
3. The schema checks the result and fills in its defaults. If it fails, the server doesn't start: Configuration validation failed. With strict: false, it starts with the settings from steps 1 and 2 as they are.

A path's variable name is the path in capitals, with each . replaced by _. Words inside a name aren't split: desk.pageSize is DESK_PAGESIZE, not DESK_PAGE_SIZE. Environment variables are always strings, so a number or boolean read from one needs a schema that converts it: z.coerce.number(), z.stringbool().

In Zod 4, .default({}) on a nested object returns {} as is, without the defaults inside it. Use .prefault({}), as above, to have the defaults filled in.

Flat mode

Without a schema, settings are every variable of the real environment plus the .env files, by name: this.config.get("DESK_WEB_URL"). In this mode a .env file wins over the real environment, the opposite of schema mode, and loadYaml is ignored.

this.config

this.config is the ConfigService: in tools, resources, agents, jobs and channels, but not prompts. Paths are dotted, like "desk.pageSize", or a variable's name in flat mode.

getConfig(this) returns the same service, and tryGetConfig(this) returns undefined when the plugin isn't installed.

Other exports

.env files

ConfigPlugin, frontmcp dev and frontmcp test read the same format:

# A comment
DESK_WEB_URL=https://desk.example.com
DESK_PAGESIZE=50
WELCOME="Hi!\nHow can we help?"

One NAME=value per line, with no spaces around =. Quotes around a value are removed, and in double quotes \n and \t become a new line and a tab. Lines starting with export, or with spaces around =, are skipped without a warning.

YAML files

desk:
  webUrl: https://staging.desk.example.com
  pageSize: 50
  regions: [eu, us]

A missing file is skipped. A file that isn't valid YAML stops the server with a YAMLException. YAML is read only with a schema; a real environment variable, like DESK_PAGESIZE, still wins over the file.

Caveats

• Settings are read once, when the server starts. A changed file or variable takes a restart.
• In a browser there are no files: FrontMCP's browser build skips .env and YAML and reads the schema's defaults and process.env where there is one (since 1.9.1; before, ConfigPlugin stopped the server with path.resolve() is not available in browser environments). So the Playground's examples read the environment and the defaults. Its server starts before any test runs, so the tests that set variables start a server of their own. YAML and .env loading were checked in Node.
• ConfigPlugin logs [config] Context property 'config' already exists on ExecutionContextBase. Skipping. at startup. It's harmless: this.config works.
• A prompt has no this.config. Use this.get(ConfigService), with ConfigService imported from @frontmcp/sdk.

frontmcp.config

The frontmcp CLI reads frontmcp.config.ts for its own commands. The server doesn't read it, and nothing in it reaches @FrontMcp except what the CLI passes as environment variables: frontmcp dev when it starts the server, and frontmcp build in the bundles it makes.

import { defineConfig } from "frontmcp";

export default defineConfig({
  name: "help-desk",
  entry: "src/main.ts",
  deployments: [{ target: "node" }, { target: "vercel" }],
  transport: { default: "http", http: { port: 4100, path: "/mcp" } },
  env: {
    shared: { LOG_LEVEL: "info" },
    dev: { DESK_WEB_URL: "http://localhost:5173" },
    test: { NODE_ENV: "test" },
  },
  test: { timeoutMs: 60_000, runInBand: true },
});

defineConfig() returns its argument; it's only there for type checking.

Finding the file

1. The --config <path> option, on the commands that read it: dev, test, inspector, eject-mcp-config and build, for every target. (Before 1.8.7 build ignored it, and FRONTMCP_CONFIG too.)
2. The FRONTMCP_CONFIG environment variable.
3. The nearest folder, from the current one up at most 10 levels, with a frontmcp.config.ts, .js, .json, .mjs or .cjs, tried in that order.
4. frontmcp build without any file uses package.json: its name without the scope, version, main as the entry, and one node deployment.

A .json file may have a "$schema" field, but the 1.9.3 frontmcp package includes no JSON Schema file to point it at.

Fields

Every level is strict: a field the CLI doesn't know fails with Invalid frontmcp.config. The last column says which command reads each field in 1.9.3, read from the CLI's published code; the node build's server, env and env.ship were also run.

The cli and mcpb deployments

A deployment's fields beyond target, outDir and env depend on its target. Those of cli and mcpb shape the program and the archive; frontmcp build reads them, and nothing reads some of them:

The setup questions that become a bundle's user settings, and an excludeTools and oauth that work, belong to an older shape of the file, without deployments, which only frontmcp build reads: the CLI reference shows it. A file with deployments refuses a setup block with Invalid frontmcp.config: Unrecognized key: "setup".

env and the port in frontmcp dev

frontmcp dev builds the server's environment in this order, each over the one before:

1. env.shared, then env.dev.
2. The real environment, with .env and .env.local added for variables it doesn't already have. So your shell and your .env files win over frontmcp.config.
3. PORT: --port, else transport.http.port, else the PORT already set, else 3000. A transport.http.port in the file wins over PORT in your shell. With transport.http.path, FRONTMCP_HTTP_ENTRY_PATH too.

frontmcp test does the same with env.test, without the port. frontmcp inspector differs: env.shared and env.dev win over your shell.

Caveats

• What a build carries. Since 1.9.0, each bundle frontmcp build makes (the node target and the others) sets its deployment's settings as environment variables when it starts, only where the environment doesn't have them already, so a variable set where it runs wins, and an option in @FrontMcp wins over both: server.http.port as PORT and server.http.socketPath as FRONTMCP_DAEMON_SOCKET (for the node and distributed targets, which listen themselves), server.http.entryPath as FRONTMCP_HTTP_ENTRY_PATH (it wins over transport.http.path), server.http.cors as the FRONTMCP_CORS_* variables, server.csp and server.headers as the response-header variables, server.cookies as the FRONTMCP_AFFINITY_COOKIE* variables, ha as FRONTMCP_HA_*, and env as itself. A node bundle with server: { http: { port: 4776, entryPath: "/rpc" } } and env: { DESK_NAME: "north" }, started with neither variable set, serves MCP at http://localhost:4776/rpc, and its tools read DESK_NAME. Before 1.9.0 only server.csp and server.headers were read, and not by the node build.
• frontmcp dev passes server.csp and server.headers to the server too.
• frontmcp build, like dev, runs from the folder of a frontmcp.config it finds in a parent folder, so a relative entry works from a subfolder. (Before 1.9.0 it stopped with Entry override not found: ./src/main.ts.)
• A bundle sets runtimeContext.target to its target, and FRONTMCP_DEPLOYMENT_MODE for the serverless and distributed targets. (Before 1.9.0, target stayed "unknown".)
• The frontmcp process-manager commands start and socket, and so the services service installs, read env.shared and env.ship from the frontmcp.config that governs the entry they start, and pass them to the server under the real environment. They read nothing else in it.
• A .ts config in a CommonJS project is compiled with esbuild, so it may import other local files; packages stay imports, and must be installed.

Usage

Reading your own settings

Give ConfigPlugin a schema with a default for each setting, and read them with this.config. Here a tool builds a link to a ticket from the help desk's web address:

import { App, ConfigPlugin, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

const settings = z.object({
  desk: z
    .object({
      webUrl: z.string().url().default("https://desk.example.com"),
      pageSize: z.coerce.number().default(20),
    })
    .prefault({}),
});

@Tool({ name: "ticket_link", description: "Link to a ticket in the help desk's web app", inputSchema: { id: z.string() } })
class TicketLink extends ToolContext {
  async execute({ id }: { id: string }) {
    return { url: `${this.config.get("desk.webUrl")}/tickets/${id}`, pageSize: this.config.getNumber("desk.pageSize") };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [TicketLink] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  plugins: [ConfigPlugin.init({ schema: settings })],
})
export default class Server {}

Overriding a setting from the environment

Each path in the schema can be set by an environment variable: desk.webUrl by DESK_WEBURL, desk.pageSize by DESK_PAGESIZE. The variables are read when a server starts, so the first test sets them and then starts a server of its own with createDirect(). The Playground's server started before any test ran, so the Call tab shows the defaults, and the second test shows it keeps them:

import { App, ConfigPlugin, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

const settings = z.object({
  desk: z
    .object({
      webUrl: z.string().url().default("https://desk.example.com"),
      pageSize: z.coerce.number().default(20),
    })
    .prefault({}),
});

@Tool({ name: "ticket_link", description: "Link to a ticket in the help desk's web app", inputSchema: { id: z.string() } })
class TicketLink extends ToolContext {
  async execute({ id }: { id: string }) {
    return { url: `${this.config.get("desk.webUrl")}/tickets/${id}`, pageSize: this.config.getNumber("desk.pageSize") };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [TicketLink] })
class HelpDeskApp {}

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  plugins: [ConfigPlugin.init({ schema: settings })],
};

@FrontMcp(config)
export default class Server {}

DESK_PAGESIZE arrives as the string "50"; z.coerce.number() makes it a number. In a deployment, set the variables in the environment, or in a .env file next to where the server starts.

Keeping defaults in a YAML file

For settings that are long, nested or shared by a team, keep them in a YAML file in version control, and override single values with environment variables where the server runs:

desk:
  webUrl: https://desk.example.com
  pageSize: 50

import { ConfigPlugin, FrontMcp, z } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

const settings = z.object({
  desk: z.object({ webUrl: z.string().url(), pageSize: z.coerce.number().default(20) }),
});

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  plugins: [ConfigPlugin.init({ schema: settings, loadYaml: true, basePath: process.cwd() })],
})
export default class Server {}

Started with DESK_WEBURL=https://staging.desk.example.com, the server has desk.webUrl from the environment and desk.pageSize: 50 from the file. The Playground has no files, so this one was checked in Node.

Reading plain environment variables

Without a schema, this.config reads any environment variable by name, with a default for when it's not set. Use it for a few values that don't need checking. They're read when the server starts too, so the test sets them before it starts its own:

import { App, ConfigPlugin, FrontMcp, Tool, ToolContext } from "@frontmcp/sdk";

@Tool({ name: "support_contact", description: "How customers can reach support", inputSchema: {} })
class SupportContact extends ToolContext {
  async execute() {
    return {
      email: this.config.get("SUPPORT_EMAIL", "help@desk.example.com"),
      phoneSupport: this.config.getBoolean("SUPPORT_PHONE_ENABLED"),
    };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [SupportContact] })
class HelpDeskApp {}

export const config = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [ConfigPlugin.init({})] };

@FrontMcp(config)
export default class Server {}

With nothing set, the Call tab shows the default email and phoneSupport: false.

Reading settings in a provider

Code that runs outside a call, like a provider's factory, has no this.config. loadConfig() reads the same sources and returns the checked settings, and a factory can share them as a typed provider. The factory runs when the server starts:

import { App, Tool, ToolContext, loadConfig, z } from "@frontmcp/sdk";

const settings = z.object({
  desk: z.object({ pageSize: z.coerce.number().default(20) }).prefault({}),
});

export abstract class DeskSettings {
  abstract desk: { pageSize: number };
}

@Tool({ name: "search_tickets", description: "Search support tickets by title", inputSchema: { query: z.string() } })
export class SearchTickets extends ToolContext {
  async execute({ query }: { query: string }) {
    return { query, limit: this.get(DeskSettings).desk.pageSize, tickets: [] };
  }
}

@App({
  id: "help-desk",
  name: "Help Desk",
  tools: [SearchTickets],
  providers: [{ provide: DeskSettings, name: "DeskSettings", inject: () => [], useFactory: () => loadConfig(settings) }],
})
export class HelpDeskApp {}

Setting up the CLI for a project

A frontmcp.config.ts at the project's root lets frontmcp dev, test and build run without options, and keeps development-only variables out of the code:

import { defineConfig } from "frontmcp";

export default defineConfig({
  name: "help-desk",
  entry: "src/main.ts",
  deployments: [{ target: "node" }],
  transport: { default: "http", http: { port: 4100, path: "/mcp" } },
  env: {
    dev: { DESK_WEBURL: "http://localhost:5173" },
  },
  clients: {
    "claude-code": { transport: "http", url: "http://127.0.0.1:4100/mcp" },
  },
});

frontmcp dev now starts src/main.ts with PORT=4100, FRONTMCP_HTTP_ENTRY_PATH=/mcp and DESK_WEBURL set, unless your shell or .env sets DESK_WEBURL already. Keep http.port and http.entryPath out of @FrontMcp, or they win over what the CLI passes. The CLI isn't part of the Playground; the loading, the file order and the error messages on this page were checked with the CLI's config loader in Node.

Troubleshooting

Configuration validation failed: … expected number, received string

The server fails to start with ConfigValidationError, and the message lists each setting that didn't fit the schema, like - desk.pageSize: Invalid input: expected number, received string. Environment variables are strings, and the schema says z.number():

import { App, ConfigPlugin, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

// 🚩 An environment variable can't be a number
export const settings = z.object({ desk: z.object({ pageSize: z.number().default(20) }).prefault({}) });

@Tool({ name: "page_size", description: "How many tickets a search returns", inputSchema: {} })
class PageSize extends ToolContext {
  async execute() {
    return { pageSize: this.config.get("desk.pageSize") };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [PageSize] })
class HelpDeskApp {}

export const config = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [ConfigPlugin.init({ schema: settings })] };

@FrontMcp(config)
export default class Server {}

With nothing set, the default 20 is a number and the server starts, so this shows up only where the variable is set. Use z.coerce.number(), and z.stringbool() for booleans. A setting with no default and no value fails the same way, as expected string, received undefined.

ConfigPlugin.init({ schema, strict: false }) lets the server start anyway, as the second test shows: it logs [config] Configuration validation failed: …; strict is false, so the settings are used as read, and this.config has the settings as they were read, the string "50" here, and none of the schema's defaults. Code that relies on the schema's types or defaults gets what the schema would have refused, so fix the schema rather than turn strict off.

Required configuration "…" is not defined

getOrThrow() found no value, and threw ConfigMissingError. In a tool it's a TOOL_EXECUTION_ERROR, and in production the client sees only Internal FrontMCP error:

import { App, ConfigPlugin, FrontMcp, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "ticket_link", description: "Link to a ticket in the help desk's web app", inputSchema: { id: z.string() } })
class TicketLink extends ToolContext {
  async execute({ id }: { id: string }) {
    return { url: `${this.config.getOrThrow("DESK_WEB_URL")}/tickets/${id}` }; // 🚩 not set
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [TicketLink] })
class HelpDeskApp {}

@FrontMcp({ info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [ConfigPlugin.init({})] })
export default class Server {}

Set the variable, or give the setting a default. A required setting is better caught at startup than in a call: put it in a schema without a default, and the server won't start without it.

Provider "ConfigService" is not available

The server has no ConfigPlugin. Add it with plugins: [ConfigPlugin.init({ ... })], or plugins: [ConfigPlugin] for the defaults. Before 1.9.4 the bare class registered nothing, so a server that lists it gets this error until it's updated.

Context classes shows the error.

A value in .env is ignored

• The file isn't where FrontMCP looks. .env is found relative to basePath, which defaults to the folder the process started in. Start the server from the project's root, or set basePath.
• The line isn't NAME=value. export NAME=value and NAME = value are skipped.
• With a schema, the name doesn't match a path. desk.pageSize is read from DESK_PAGESIZE only. DESK_PAGE_SIZE is ignored.
• The real environment has the same variable. With a schema, it wins over .env. (Without one, .env wins.)
• It's one of FrontMCP's own variables. See the next entry.

PORT in .env is ignored

FrontMCP reads PORT when it reads the @FrontMcp options, as the decorated class is imported. ConfigPlugin copies .env into process.env later, when the server starts, so the server listens on 3000 though process.env.PORT is set afterwards. Variables FrontMCP reads later, like FRONTMCP_BIND_ADDRESS, do take the file's value. Load the file before the server starts instead: frontmcp dev does, and so does node --env-file=.env dist/main.js.

PORT has no effect

Either @FrontMcp({ http: { port } }) sets a port, which wins, or frontmcp.config's transport.http.port does, which frontmcp dev puts before PORT. Remove the one you don't want, or pass frontmcp dev --port.

Invalid frontmcp.config

The CLI lists every field that didn't fit:

Invalid frontmcp.config:
  - name: Must be alphanumeric with .-_ only
  - deployments.0.target: Invalid discriminator value. Expected 'node' | 'distributed' | 'cli' | 'vercel' | 'lambda' | 'cloudflare' | 'browser' | 'sdk' | 'mcpb'
  - : Unrecognized key: "extra"

An empty path, as in the last line, means the top level. Every object in the file is strict, so a misspelled field is an error rather than ignored. A --config path that doesn't exist fails with Config file not found.

A setting in frontmcp.config does nothing

• The server runs from source. Only frontmcp dev (for transport, env.shared, env.dev, server.csp and server.headers) and the bundles of frontmcp build (for a deployment's server, ha and env) pass settings on; tsx src/main.ts or your own runner gets none of them.
• The environment already has the variable. A bundle sets its defaults only where nothing set them first.
• @FrontMcp sets the option. An explicit http.port, http.entryPath or http.cors wins over what the CLI passes.
• FrontMCP 1.8.7 or earlier. Its CLI accepted deployments[].server.http and server.cookies, deployments[].ha, deployments[].env, env.ship and skills, and read none of them; nor server.csp and server.headers in a node build. See the caveats.