Skip to main content
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:
  1. frontmcp.config.ts
  2. frontmcp.config.js
  3. frontmcp.config.json
  4. frontmcp.config.mjs
  5. frontmcp.config.cjs
  6. 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

FieldTypeRequiredDescription
namestringYesServer name (kebab-case, no spaces)
versionstringNoServer version
entrystringNoCustom entry file path
nodeVersionstringNoTarget Node.js version
deploymentsDeploymentTarget[]YesOne or more deployment targets
buildobjectNoBuild-specific options (esbuild config, dependencies)

​
Deployment Targets

Each entry in deployments defines a build target with independent settings:
TargetDescriptionTransportStorage
nodeStandalone Node.js serverStreamable HTTP, SSE, stdioRedis, SQLite, memory
distributedMulti-pod with HAStreamable HTTPRedis (required)
vercelVercel FunctionsStreamable HTTPVercel KV
lambdaAWS LambdaStreamable HTTPDynamoDB, ElastiCache
cloudflareCloudflare WorkersStreamable HTTPKV, Durable Objects
browserBrowser bundleIn-memoryMemory only
cliStandalone binarystdioSQLite, memory
sdkLibrary for embeddingDirect (in-process)Configurable
mcpbMCP Bundle archive (see MCPB)stdioSQLite, memory

​
Deployment Target Fields

FieldTypeDescription
targetstringOne of the 9 target types above
serverServerConfigHTTP, CORS, CSP, and security header settings
haHaConfigHA settings (distributed target only)
cliCliConfigCLI-specific settings (cli target only)
jsbooleanGenerate .js bundle instead of native binary (cli target)
envRecordPer-target environment variables

​
MCPB-Only Fields

The mcpb target supports additional fields for MCP Bundle metadata:
FieldTypeDescription
displayNamestringHuman-friendly bundle title shown in the installer
longDescriptionstringMarkdown description for the extension details page
author{ name, email?, url? }Overrides parsed package.json.author
licensestringSPDX license identifier
homepagestringProject homepage URL
repositorystring | { type, url }Source repository
documentationstringDocumentation URL
supportstringSupport / issues URL
iconstringIcon path relative to project root (PNG)
keywordsstring[]Keywords for client search
privacyPoliciesstring[]Privacy policy URLs for external services this server talks to
compatibilityobject{ claude_desktop?, platforms?, runtimes? } constraints
userConfigRecordMCPB 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
includeNodeModulesbooleanInclude server/node_modules/ in the archive (off by default)
deterministicbooleanProduce 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

FieldTypeDefaultDescription
portnumber3000HTTP listen port
socketPathstring---Unix socket path (overrides port)
entryPathstring/Base path for all endpoints
corsobject---CORS configuration (origin, credentials)
portRange[number, number]---Auto-find available port in range

​
CSP Options

FieldTypeDefaultDescription
enabledbooleanfalseEnable CSP headers
directivesRecord---Directive name to value(s) map (e.g., { 'default-src': "'self'" })
reportUristring---URI for CSP violation reports
reportOnlybooleanfalseUse Content-Security-Policy-Report-Only header

​
Security Headers

FieldTypeDefaultDescription
hstsstring---Strict-Transport-Security value
contentTypeOptionsstringnosniffX-Content-Type-Options value
frameOptionsstringDENYX-Frame-Options value

​
HA Configuration

FieldTypeDefaultDescription
heartbeatIntervalMsnumber10000Heartbeat write interval
heartbeatTtlMsnumber30000Heartbeat TTL (2-3x interval)
takeoverGracePeriodMsnumber5000Grace period before takeover
redisKeyPrefixstringmcp: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