Configuration File

FrontMCP uses a typed configuration file to define project settings, deployment targets, server configuration, and security policies. The file supports TypeScript, JavaScript, and JSON formats with full IDE autocomplete.

Quick Start

Create frontmcp.config.ts in your project root:

import { defineConfig } from '@frontmcp/cli';

export default defineConfig({
  name: 'my-server',
  deployments: [{ target: 'node' }],
});

The defineConfig() helper is a pass-through that enables IDE type hints and autocomplete.

File Resolution Order

FrontMCP searches for configuration files in this order:

frontmcp.config.ts
frontmcp.config.js
frontmcp.config.json
frontmcp.config.mjs
frontmcp.config.cjs
Fallback: derives minimal config from package.json (name, default node target)

When using JSON format, add "$schema" for autocomplete in VS Code and WebStorm:

{
  "$schema": "./node_modules/@frontmcp/cli/frontmcp.schema.json",
  "name": "my-server",
  "deployments": [{ "target": "node" }]
}

Top-Level Fields

Field	Type	Required	Description
`name`	string	Yes	Server name (kebab-case, no spaces)
`version`	string	No	Server version
`entry`	string	No	Custom entry file path
`nodeVersion`	string	No	Target Node.js version
`deployments`	DeploymentTarget[]	Yes	One or more deployment targets
`build`	object	No	Build-specific options (esbuild config, dependencies)

Deployment Targets

Each entry in deployments defines a build target with independent settings:

Target	Description	Transport	Storage
`node`	Standalone Node.js server	Streamable HTTP, SSE, stdio	Redis, SQLite, memory
`distributed`	Multi-pod with HA	Streamable HTTP	Redis (required)
`vercel`	Vercel Functions	Streamable HTTP	Vercel KV
`lambda`	AWS Lambda	Streamable HTTP	DynamoDB, ElastiCache
`cloudflare`	Cloudflare Workers	Streamable HTTP	KV, Durable Objects
`browser`	Browser bundle	In-memory	Memory only
`cli`	Standalone binary	stdio	SQLite, memory
`sdk`	Library for embedding	Direct (in-process)	Configurable
`mcpb`	MCP Bundle archive (see MCPB)	stdio	SQLite, memory

Deployment Target Fields

Field	Type	Description
`target`	string	One of the 9 target types above
`server`	ServerConfig	HTTP, CORS, CSP, and security header settings
`ha`	HaConfig	HA settings (distributed target only)
`cli`	CliConfig	CLI-specific settings (cli target only)
`js`	boolean	Generate .js bundle instead of native binary (cli target)
`env`	Record	Per-target environment variables

MCPB-Only Fields

The mcpb target supports additional fields for MCP Bundle metadata:

Field	Type	Description
`displayName`	string	Human-friendly bundle title shown in the installer
`longDescription`	string	Markdown description for the extension details page
`author`	`{ name, email?, url? }`	Overrides parsed `package.json.author`
`license`	string	SPDX license identifier
`homepage`	string	Project homepage URL
`repository`	string \| `{ type, url }`	Source repository
`documentation`	string	Documentation URL
`support`	string	Support / issues URL
`icon`	string	Icon path relative to project root (PNG)
`keywords`	string[]	Keywords for client search
`privacyPolicies`	string[]	Privacy policy URLs for external services this server talks to
`compatibility`	object	`{ claude_desktop?, platforms?, runtimes? }` constraints
`userConfig`	Record	MCPB `user_config` overrides (type, min/max, etc.) — merged with translated `setup.steps`
`sea`	`{ enabled?, mergeFrom? }`	Build SEA binary for the host and/or merge pre-built binaries
`includeNodeModules`	boolean	Include `server/node_modules/` in the archive (off by default)
`deterministic`	boolean	Produce byte-identical archives across runs (defaults to `true`)

Server Configuration

export default defineConfig({
  name: 'my-server',
  deployments: [{
    target: 'node',
    server: {
      http: {
        port: 3000,
        socketPath: '/tmp/mcp.sock',  // Unix socket (mutually exclusive with port)
        entryPath: '/',
        cors: {
          origin: 'https://app.example.com',
          credentials: true,
        },
        portRange: [3000, 3010],  // Auto-find available port in range
      },
      csp: {
        enabled: true,
        directives: {
          'default-src': "'self'",
          'script-src': "'self' https://cdn.example.com",
        },
        reportUri: 'https://report.example.com/csp',
        reportOnly: false,
      },
      headers: {
        hsts: 'max-age=31536000; includeSubDomains',
        contentTypeOptions: 'nosniff',
        frameOptions: 'DENY',
      },
      cookies: {
        secure: true,
        sameSite: 'Lax',
      },
    },
  }],
});

HTTP Options

Field	Type	Default	Description
`port`	number	3000	HTTP listen port
`socketPath`	string	---	Unix socket path (overrides port)
`entryPath`	string	`/`	Base path for all endpoints
`cors`	object	---	CORS configuration (origin, credentials)
`portRange`	[number, number]	---	Auto-find available port in range

CSP Options

Field	Type	Default	Description
`enabled`	boolean	false	Enable CSP headers
`directives`	Record	---	Directive name to value(s) map (e.g., `{ 'default-src': "'self'" }`)
`reportUri`	string	---	URI for CSP violation reports
`reportOnly`	boolean	false	Use `Content-Security-Policy-Report-Only` header

Security Headers

Field	Type	Default	Description
`hsts`	string	---	`Strict-Transport-Security` value
`contentTypeOptions`	string	`nosniff`	`X-Content-Type-Options` value
`frameOptions`	string	`DENY`	`X-Frame-Options` value

HA Configuration

Field	Type	Default	Description
`heartbeatIntervalMs`	number	10000	Heartbeat write interval
`heartbeatTtlMs`	number	30000	Heartbeat TTL (2-3x interval)
`takeoverGracePeriodMs`	number	5000	Grace period before takeover
`redisKeyPrefix`	string	`mcp:ha:`	Redis key prefix

Multi-Target Example

Deploy the same server to Node.js, distributed, and Vercel:

import { defineConfig } from '@frontmcp/cli';

export default defineConfig({
  name: 'my-server',
  version: '1.0.0',
  deployments: [
    {
      target: 'node',
      server: { http: { port: 3000 } },
    },
    {
      target: 'distributed',
      ha: { heartbeatIntervalMs: 5000 },
      server: {
        csp: {
          enabled: true,
          directives: { 'default-src': "'self'", 'upgrade-insecure-requests': '' },
        },
        headers: { hsts: 'max-age=31536000; includeSubDomains' },
      },
    },
    {
      target: 'vercel',
    },
  ],
});

Build each target independently:

frontmcp build --target node
frontmcp build --target distributed
frontmcp build --target vercel

Helper Functions

import { defineConfig, loadFrontMcpConfig, findDeployment, getDeploymentTargets } from '@frontmcp/cli';

// Load config from a directory
const config = await loadFrontMcpConfig(process.cwd());

// Find a specific deployment target
const distributed = findDeployment(config, 'distributed');

// List all configured targets
const targets = getDeploymentTargets(config); // ['node', 'distributed', 'vercel']

Production Build

Build and deploy guide

High Availability

Multi-pod deployment with session failover

Security Headers

CSP and security header configuration

Runtime Modes

Standalone, distributed, and serverless modes

Get Started

FrontMCP

Features

Extensibility

Testing

React SDK

Guides

Quick Start

File Resolution Order

Top-Level Fields

Deployment Targets

Deployment Target Fields

MCPB-Only Fields

Server Configuration

HTTP Options

CSP Options

Security Headers

HA Configuration

Multi-Target Example

Helper Functions

Production Build

High Availability

Security Headers

Runtime Modes

​Quick Start

​File Resolution Order

​Top-Level Fields

​Deployment Targets

​Deployment Target Fields

​MCPB-Only Fields

​Server Configuration

​HTTP Options

​CSP Options

​Security Headers

​HA Configuration

​Multi-Target Example

​Helper Functions

​Related

Production Build

High Availability

Security Headers

Runtime Modes

Quick Start

File Resolution Order

Top-Level Fields

Deployment Targets

Deployment Target Fields

MCPB-Only Fields

Server Configuration

HTTP Options

CSP Options

Security Headers

HA Configuration

Multi-Target Example

Helper Functions

Related