Skip to main content

​
Class Definition

export class FrontMcpServerInstance extends FrontMcpServer {
  config: HttpOptions;
  host: HostServerAdapter;
}

​
Properties

PropertyTypeDescription
configHttpOptionsHTTP configuration
hostHostServerAdapterHost adapter (Express, etc.)

​
Methods

​
registerMiddleware(entryPath, handler)

Register middleware at a specific entry path. 
registerMiddleware(entryPath: string, handler: ServerRequestHandler): void

​
registerRoute(method, path, handler)

Register an HTTP route. 
registerRoute(
  method: HttpMethod,
  path: string,
  handler: ServerRequestHandler
): void

​
prepare()

Prepare routes without starting the server. 
prepare(): void
  • Registers /health endpoint automatically
  • Prepares all configured routes
  • Call before getHandler() for serverless

​
getHandler()

Get the underlying HTTP handler for serverless export. 
getHandler(): unknown
Returns the host adapter’s handler (e.g., Express app).

​
start()

Start the server on the configured TCP port, or on a Unix domain socket when HttpOptions.socketPath is set (Unix socket overrides port). 
start(): Promise<void>

​
HttpOptions

interface HttpOptions {
  port?: number;                                   // default 3001
  entryPath?: string;                              // MCP JSON-RPC entry path (default: '')
  hostFactory?:                                    // Custom host adapter (instance or factory)
    | FrontMcpServer
    | ((config: HttpOptions) => FrontMcpServer);
  socketPath?: string;                             // Unix socket path (overrides port)
  cors?: CorsOptions | false;                      // CORS config (default: permissive with built-in adapter)
  security?: SecurityOptions;                      // Transport hardening (strict, bindAddress, DNS rebinding protection)
}

​
Host Adapters

​
Default (Express)

Express is the default host adapter: 
@FrontMcp({
  info: { name: 'Server', version: '1.0.0' },
  apps: [MyApp],
  http: { port: 3001 },
  // Uses ExpressHostAdapter by default
})

​
Custom Host Factory

Provide a custom host adapter: 
import { FastifyHostAdapter } from './adapters/fastify';

@FrontMcp({
  info: { name: 'Server', version: '1.0.0' },
  apps: [MyApp],
  http: {
    port: 3000,
    hostFactory: (config) => new FastifyHostAdapter(config),
  },
})

​
Host Adapter Interface

export abstract class HostServerAdapter extends FrontMcpServer {
  abstract prepare(): void;
  abstract getHandler(): unknown;
  abstract start(port: number, bindAddress?: string): Promise<void> | void;
  abstract start(socketPath: string): Promise<void> | void;
  abstract start(
    portOrSocketPath?: number | string,
    bindAddress?: string
  ): Promise<void> | void;
}

​
Usage Examples

​
Standard Deployment

import { FrontMcpInstance } from '@frontmcp/sdk';
import config from './server';

// bootstrap() handles server creation and start
await FrontMcpInstance.bootstrap(config);

​
Manual Server Access

import { FrontMcpInstance, FrontMcpServer } from '@frontmcp/sdk';

const instance = await FrontMcpInstance.createForGraph(config);
await instance.ready;

// Access server from providers
const server = instance.providers.get(FrontMcpServer);

// Register additional routes
server.registerRoute('GET', '/custom', (req, res) => {
  res.json({ custom: true });
});

// Start server
await server.start();

​
Serverless Deployment

// api/mcp.ts
import { FrontMcpInstance } from '@frontmcp/sdk';
import config from '../src/server';

// createHandler() prepares and returns the handler
export default FrontMcpInstance.createHandler(config);

​
Custom CORS

@FrontMcp({
  info: { name: 'Server', version: '1.0.0' },
  apps: [MyApp],
  http: {
    port: 3001,
    cors: {
      origin: ['https://app.example.com', 'http://localhost:3000'],
      credentials: true,
      maxAge: 86400,
    },
  },
})

​
Health & Readiness Endpoints

FrontMCP automatically registers health and readiness endpoints: 
# Liveness probe (lightweight, no I/O)
curl http://localhost:3001/healthz
# {"status":"ok","server":{"name":"my-server","version":"1.0.0"},"runtime":{"platform":"linux","runtime":"node",...},"uptime":42.5}

# Readiness probe (deep dependency checks)
curl http://localhost:3001/readyz
# {"status":"ready","totalLatencyMs":15,"catalog":{"toolsHash":"a1b2...","toolCount":5,...},"probes":{"session-store":{"status":"healthy","latencyMs":3}}}

# Legacy endpoint (alias for /healthz)
curl http://localhost:3001/health
EndpointPurposeI/ORuntime
/healthzLiveness probeNoneAll
/readyzReadiness probe with dependency checksYesNode, Bun, Deno, Browser
/healthLegacy alias for /healthzNoneAll
The readiness endpoint automatically discovers and probes session stores (Redis/Vercel KV) and remote MCP app connections. Add custom probes for databases and APIs via health.probes.

Health Checks Guide

Full configuration, custom probes, Kubernetes & Docker examples

FrontMcpInstance

Server bootstrap

@FrontMcp

Server configuration

Serverless Deployment

Serverless guide

Production Build

Production deployment