The FrontMCP Server

FrontMCP servers are defined with a single decorator, @FrontMcp({ ... }). This page shows the minimal config and then every top-level option you can use. Deep dives live in the pages listed under Servers.

Minimal server

import { FrontMcp } from '@frontmcp/sdk';
import MyApp from './my.app';

@FrontMcp({
  info: { name: 'My Server', version: '0.1.0' },
  apps: [MyApp],
})
export default class Server {}

Required:

info.name (string)
info.version (string)
apps (at least one app)

Everything else is optional with sensible defaults.

Full configuration (at a glance)

@FrontMcp({
  /** Required */
  info: {
    name: 'Expense MCP Server',
    version: '1.0.0',
    title?: 'Human title',
    websiteUrl?: 'https://example.com',
    icons?: Icon[], // MCP Icon[]
  },
  apps: [/* App classes */],

Info field descriptions:

Field	Description
`name`	Server name shown in MCP discovery
`version`	Semantic version for clients to track
`title`	Optional human-readable title
`websiteUrl`	Link to documentation or homepage
`icons`	MCP Icon array for visual branding

@FrontMcp({
  /** Optional */
  serve?: true,                 // default true (auto-boot)
  splitByApp?: false,           // app composition mode
  providers?: [/* provider classes/factories/values */],

  http?: {
    port?: 3001,                // default 3001
    entryPath?: '',             // MUST match PRM resourcePath in .well-known
    hostFactory?: /* custom host */,
  },

  /** Transport & session lifecycle (NEW in v0.6) */
  transport?: {
    // Session lifecycle
    sessionMode?: 'stateful' | 'stateless',     // default 'stateful'
    transportIdMode?: 'uuid' | 'jwt',           // default 'uuid'
    platformDetection?: { customOnly?: boolean },

    // Protocol switches
    enableLegacySSE?: false,
    enableSseListener?: true,
    enableStreamableHttp?: true,
    enableStatelessHttp?: false,
    enableStatefulHttp?: false,
    requireSessionForStreamable?: true,

    // Session persistence (Redis-backed)
    persistence?: {
      enabled?: false,
      defaultTtlMs?: 3600000,   // 1 hour
    },
  },

  /** Shared Redis config (NEW in v0.6) */
  redis?: {
    host: 'localhost',
    port?: 6379,
    password?: string,
    db?: 0,
    tls?: false,
    keyPrefix?: 'mcp:',
    defaultTtlMs?: 3600000,
  },

  logging?: {
    level?: LogLevel.Info,      // Debug | VERBOSE | Info | Warn | Error | Off
    enableConsole?: true,       // default true
    prefix?: string,
    transports?: [/* custom log transports */],
  },

  /** Server-level default auth (omit if splitByApp: true) */
  auth?: (
    | { type: 'remote', name: string, baseUrl: string, ... }
    | { type: 'local',  id: string,   name: string,   ... }
  ),
})

Composition mode

FrontMCP can host many apps. Choose how they’re exposed:

Multi-App (default): splitByApp: false One server scope. You may configure server-level auth and all apps inherit it (apps can still override with app-level auth).
Split-By-App: splitByApp: true Each app is isolated under its own scope/base path (for example /billing). Streamable HTTP, the /message SSE endpoint, and OAuth issuers reuse that scope automatically. Server-level auth is disallowed; configure auth per app. (See Authentication → Overview.)

If you’re offering multiple products or tenants, splitByApp: true gives clean separation and per-app auth.

HTTP transport

http: {
  port?: number;      // default 3001
  entryPath?: string; // default ''; MUST match the PRM resourcePath in .well-known
  hostFactory?: FrontMcpServer | ((cfg) => FrontMcpServer);
}

Field	Description
`port`	HTTP listening port (default: 3001)
`entryPath`	JSON-RPC entry path; must match `.well-known` discovery
`hostFactory`	Custom host implementation for advanced setups

Port: listening port for Streamable HTTP.
entryPath: your MCP JSON-RPC entry ('' or '/mcp'). Must align with discovery.
hostFactory: advanced — provide/construct a custom host implementation.
Split-by-app scopes: when splitByApp is enabled, clients hit <entryPath>/<appId> (for example /mcp/billing) and subscribe via <entryPath>/<appId>/message; FrontMCP handles the prefixing.

Transport

New in v0.6: Transport configuration has moved from auth.transport and session to a dedicated top-level transport property. This separates transport/session lifecycle concerns from authentication. See Migration below.

The transport config controls session lifecycle, protocol switches, and session persistence. Configure it at the server level or per-app when using splitByApp: true.

@FrontMcp({
  transport: {
    // Session lifecycle
    sessionMode: 'stateful',
    transportIdMode: 'uuid',
    platformDetection: { customOnly: false },

    // Protocol switches
    enableLegacySSE: false,
    enableSseListener: true,
    enableStreamableHttp: true,
    enableStatelessHttp: false,
    enableStatefulHttp: false,
    requireSessionForStreamable: true,

    // Session persistence
    persistence: {
      enabled: true,
      defaultTtlMs: 3600000,
    },
  },
})

Session Lifecycle

Option	Default	Description
`sessionMode`	`'stateful'`	`'stateful'` (server-side store) or `'stateless'` (JWT-based)
`transportIdMode`	`'uuid'`	`'uuid'` (per-node identity) or `'jwt'` (signed, distributed)
`platformDetection`	`undefined`	Platform detection config; set `customOnly: true` to skip built-in mappings

transport: {
  sessionMode: 'stateful',    // Server-side session store
  transportIdMode: 'uuid',    // Random UUID per transport
}

Protocol Switches

Choose which MCP transports to enable based on your deployment:

Option	Default	When to enable	Notes
`enableStreamableHttp`	`true`	Modern MCP clients (Claude Desktop, Cursor, Rendezvous)	Primary transport; streams JSON-RPC over HTTP.
`enableStatefulHttp`	`false`	Local previews, OAuth consent screens, Jest suites	JSON-only endpoint for requests without SSE—handy for testing and health checks.
`enableStatelessHttp`	`false`	Public mode or CI agents that cannot run `initialize`	Singleton transports that skip initialization handshake.
`enableSseListener`	`true`	Manual SSE subscribers or dashboards	Controls `GET /message` endpoint. Disable to reduce long-lived sockets.
`enableLegacySSE`	`false`	Supporting pre-Streamable clients temporarily	Legacy HTTP + SSE combo—plan to remove once clients upgrade.
`requireSessionForStreamable`	`true`	Public demos or scripted tests	Set `false` to let Streamable HTTP requests bootstrap themselves.

Leave enableStatelessHttp off in production unless you fully trust the client surface. Stateless transports reuse process-wide connections, which is perfect for CI but can bypass fine-grained session teardown.

@FrontMcp({
  transport: {
    enableStreamableHttp: true,
    enableStatefulHttp: true,      // JSON fallback for previews
    enableStatelessHttp: false,    // keep anonymous traffic scoped
    requireSessionForStreamable: false,
  },
})

Session Persistence

Enable Redis-backed session persistence for distributed deployments or session recovery:

@FrontMcp({
  redis: {
    host: 'redis.example.com',
    port: 6379,
  },
  transport: {
    persistence: {
      enabled: true,
      defaultTtlMs: 7200000, // 2 hours
    },
  },
})

Option	Default	Description
`enabled`	`false`	Enable session persistence
`defaultTtlMs`	`3600000`	Session TTL in milliseconds (1 hour)

Session persistence uses the top-level redis config. Configure redis once and reference it from both transport.persistence and auth.tokenStorage.

You can apply different transport policies per app when splitByApp: true. Sensitive apps stay stream-only with strict session IDs, while demo or health-check apps can enable stateful/stateless HTTP for easier automation.

Redis

New in v0.6: Redis configuration has moved to a dedicated top-level redis property, shared by both transport.persistence and auth.tokenStorage.

Configure Redis once at the server level for use across features:

@FrontMcp({
  redis: {
    host: 'redis.example.com',
    port: 6379,
    password: 'secret',
    db: 0,
    tls: true,
    keyPrefix: 'mcp:',
    defaultTtlMs: 3600000,
  },
})

Option	Default	Description
`host`	(required)	Redis server hostname
`port`	`6379`	Redis server port
`password`	-	Optional authentication password
`db`	`0`	Redis database index
`tls`	`false`	Enable TLS/SSL connection
`keyPrefix`	`'mcp:'`	Prefix for all Redis keys
`defaultTtlMs`	`3600000`	Default TTL for cached data (1 hour)

Usage with Features

The redis config is automatically used by:

Session persistence (transport.persistence) — stores session state for recovery
Token storage (auth.tokenStorage: { type: 'redis' }) — stores refresh tokens securely

@FrontMcp({
  redis: {
    host: 'localhost',
    keyPrefix: 'myapp:',
  },
  transport: {
    persistence: { enabled: true },
  },
  auth: {
    mode: 'orchestrated',
    type: 'local',
    tokenStorage: { type: 'redis' },
  },
})

Migration from `auth.transport`

Deprecated: The auth.transport and session properties are deprecated and will be removed in v1.0.0. Migrate to the top-level transport config.

FrontMCP automatically migrates old configs at runtime with a deprecation warning. Update your config manually to remove the warning:

@FrontMcp({
  session: {
    sessionMode: 'stateful',
    transportIdMode: 'uuid',
  },
  auth: {
    mode: 'orchestrated',
    type: 'local',
    transport: {
      enableStreamableHttp: true,
      enableStatefulHttp: true,
      recreation: {
        enabled: true,
        redis: { host: 'localhost' },
      },
    },
  },
})

Migration Mapping

Old Path	New Path
`session.sessionMode`	`transport.sessionMode`
`session.transportIdMode`	`transport.transportIdMode`
`session.platformDetection`	`transport.platformDetection`
`auth.transport.enableLegacySSE`	`transport.enableLegacySSE`
`auth.transport.enableSseListener`	`transport.enableSseListener`
`auth.transport.enableStreamableHttp`	`transport.enableStreamableHttp`
`auth.transport.enableStatelessHttp`	`transport.enableStatelessHttp`
`auth.transport.enableStatefulHttp`	`transport.enableStatefulHttp`
`auth.transport.requireSessionForStreamable`	`transport.requireSessionForStreamable`
`auth.transport.recreation`	`transport.persistence`
`auth.transport.recreation.redis`	`redis` (top-level)

Logging

logging: {
  level?: LogLevel;        // default Info
  enableConsole?: boolean; // default true
  prefix?: string;
  transports?: LogTransportType[]; // custom sinks via @FrontMcpLogTransport
}

Field	Description
`level`	Minimum log level: Debug, Verbose, Info, Warn, Error, Off
`enableConsole`	Whether to output to stdout (default: true)
`prefix`	Optional prefix for all log messages
`transports`	Custom log transport implementations

Use custom log transports for shipping logs to external systems; console remains on by default.

Global providers

providers: [
  /* Provider classes/factories/values */
];

Define DI-style singletons available to all apps (and their tools/plugins). Scopes are supported at the provider level (GLOBAL, SESSION, REQUEST).

Authentication (server level)

Server-level auth sets the default auth for all apps (unless splitByApp: true, where auth must be per-app).

Remote OAuth (encapsulated external IdP)

auth: {
  type: 'remote',
  name: 'frontegg',
  baseUrl: 'https://auth.example.com',
  dcrEnabled?: boolean,
  clientId?: string | ((info) => string), // for non-DCR via local proxy
  mode?: 'orchestrated' | 'transparent',
  allowAnonymous?: boolean,
  consent?: boolean,
  scopes?: string[],
  grantTypes?: ['authorization_code','refresh_token'],
  authEndpoint?: string,
  tokenEndpoint?: string,
  registrationEndpoint?: string,
  userInfoEndpoint?: string,
  jwks?: JSONWebKeySet,
  jwksUri?: string,
}

Local OAuth (built-in AS)

auth: {
  type: 'local',
  id: 'local',
  name: 'Local Auth',
  scopes?: string[],
  grantTypes?: ['authorization_code','refresh_token'],
  allowAnonymous?: boolean,  // default true
  consent?: boolean,         // show tool/resource/prompt consent
  jwks?: JSONWebKeySet,      // inline keys (optional)
  signKey?: JWK | Uint8Array // private key (optional; auto-gen if omitted)
}

Apps can also define their own auth (and mark themselves standalone) to expose an isolated auth surface — useful when mixing public and private apps under one server.

Bootstrapping & discovery

Version safety: on boot, FrontMCP checks that all @frontmcp/* packages are aligned and throws a clear “version mismatch” error otherwise.

If you disable serve, you’re responsible for calling the core bootstrap yourself.

Common starting points

Single app, default everything: minimal sample above.
Multiple apps, shared auth: omit splitByApp, set server-level auth.
Isolated apps with per-app auth: set splitByApp: true, configure auth in each app.

Best Practices

Do:

Start with minimal config and add options as needed
Use splitByApp: true for multi-tenant deployments
Use top-level transport config (not auth.transport or session)
Configure redis at top-level for shared use across features
Use stateful session mode with Redis for production deployments
Enable persistence for distributed or high-availability setups
Set log level to Info or higher in production

Don’t:

Configure server-level auth when using splitByApp: true
Use deprecated auth.transport or session — migrate to transport
Disable serve unless you’re managing bootstrap manually
Use stateless session mode with short-lived upstream tokens
Enable enableStatelessHttp in production without trust boundaries
Leave enableConsole: true in containerized production (use transports)

Next up: learn how to structure Apps, Tools, Resources, and Prompts in the Core Components section.

Get Started

Servers

Authentication

Extensibility

Adapters

Plugins

Testing

Guides

Deployment

The FrontMCP Server

Minimal server

Full configuration (at a glance)

Composition mode

HTTP transport

Transport

Session Lifecycle

Protocol Switches

Session Persistence

Redis

Usage with Features

Migration from `auth.transport`

Migration Mapping

Logging

Global providers

Authentication (server level)

Remote OAuth (encapsulated external IdP)

Local OAuth (built-in AS)

Bootstrapping & discovery

Common starting points

Best Practices

Get Started

Servers

Authentication

Extensibility

Adapters

Plugins

Testing

Guides

Deployment

​Minimal server

​Full configuration (at a glance)

​Composition mode

​HTTP transport

​Transport

​Session Lifecycle

​Protocol Switches

​Session Persistence

​Redis

​Usage with Features

​Migration from auth.transport

​Migration Mapping

​Logging

​Global providers

​Authentication (server level)

​Remote OAuth (encapsulated external IdP)

​Local OAuth (built-in AS)

​Bootstrapping & discovery

​Common starting points

​Best Practices

Minimal server

Full configuration (at a glance)

Composition mode

HTTP transport

Transport

Session Lifecycle

Protocol Switches

Session Persistence

Redis

Usage with Features

Migration from `auth.transport`

Migration Mapping

Logging

Global providers

Authentication (server level)

Remote OAuth (encapsulated external IdP)

Local OAuth (built-in AS)

Bootstrapping & discovery

Common starting points

Best Practices