FrontMcpInstance

Class Definition

export class FrontMcpInstance implements FrontMcpInterface {
  config: FrontMcpConfigType;
  readonly ready: Promise<void>;
}

Properties

Property	Type	Description
`config`	`FrontMcpConfigType`	Parsed server configuration
`ready`	`Promise<void>`	Promise that resolves when fully initialized

Factory Methods

bootstrap(options)

Create and start an HTTP server.

static async bootstrap(
  options: FrontMcpConfigInput | FrontMcpConfigType
): Promise<void>

Best for: Standalone HTTP server deployments.

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

await FrontMcpInstance.bootstrap(config);
// Server running on configured port

createHandler(options)

Create a serverless handler without starting a server.

static async createHandler(options: FrontMcpConfigInput | FrontMcpConfigType): Promise<unknown>

Best for: Serverless deployments (Vercel, AWS Lambda).

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

export default FrontMcpInstance.createHandler(config);

createFetchHandler(options)

Create a Web-standard fetch handler, (request: Request) => Promise<Response>, for runtimes without Node req/res: Cloudflare Workers, Deno and Bun.

static async createFetchHandler(options: FrontMcpConfigInput | FrontMcpConfigType): Promise<WebFetchHandler>

It accepts the same config as @FrontMcp(). A server the startup checks refuse (an approval or featureFlag field no installed plugin enforces, authorities without the authorities option, a missing secret) rejects here, as with createDirect(). On an edge isolate (Cloudflare Workers, Vercel Edge, Deno) the instance is built on the first request instead, because isolates forbid timers and I/O at module evaluation: the checks the config’s metadata settles still reject here, and a failed build is answered, never thrown: a configuration fault (a missing secret, a startup check, a config the schema refuses) with a 500 { "error": "server_misconfigured", "code", "message" } body, anything else (a remote that refused the connection, a package that failed to load) with a 503 { "error": "server_unavailable", "code": "SERVER_START_FAILED" } body and Retry-After. A failed build is kept until a retry delay passes (1 s, doubling up to 60 s); the first request after it builds again. Requests run through the same http:request flow as the Express host, with the same request context: the user agent, x-frontmcp-* headers, traceparent and the MCP 2026-07-28 _meta client info.

// worker entry
const handler = await FrontMcpInstance.createFetchHandler(config);
export default { fetch: (request: Request) => handler(request) };

// Deno / Bun: forward the runtime's second argument so the handler sees the client IP
Deno.serve((request, info) => handler(request, info));
Bun.serve({ fetch: (request, server) => handler(request, server) });

The client IP comes from Deno’s info.remoteAddr, Bun’s server.requestIP(request), or, only on Cloudflare Workers, the CF-Connecting-IP header. The handler is stateless: session-based (2025-06-18) clients get no Mcp-Session-Id and every request stands alone. See Cloudflare Worker for stateful sessions with Durable Objects.

createDirect(options)

Create a DirectMcpServer for programmatic access.

static async createDirect(options: FrontMcpConfigInput): Promise<DirectMcpServer>

Best for: Testing, embedding, CLI tools, agent backends.

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

const server = await FrontMcpInstance.createDirect(config);

// Use programmatically
const tools = await server.listTools();
const result = await server.callTool('my_tool', { arg: 'value' });

// Cleanup
await server.dispose();

createForGraph(options)

Create an instance for introspection without starting server.

static async createForGraph(options: FrontMcpConfigInput): Promise<FrontMcpInstance>

Best for: Graph visualization, introspection, analysis.

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

const instance = await FrontMcpInstance.createForGraph(config);
const scopes = instance.getScopes();

// Analyze registries
scopes.forEach(scope => {
  console.log('Tools:', scope.tools.getTools().length);
  console.log('Resources:', scope.resources.getResources().length);
});

runStdio(optionsOrClass)

Run the server over stdio (stdin/stdout JSON-RPC). No HTTP/TCP port is bound — the HTTP server is disabled for this entry point.

static async runStdio(optionsOrClass: ConfigOrServerClass): Promise<void>

Best for: Claude Desktop, Claude Code, Cursor, and other stdio MCP clients. Accepts either a @FrontMcp-decorated class or the same config object you pass to @FrontMcp().

// stdio.ts — config kept in its own module (no @FrontMcp decorator imported here)
import { FrontMcpInstance } from '@frontmcp/sdk';
import { serverConfig } from './server-config';

await FrontMcpInstance.runStdio(serverConfig);
// Never returns until the connection closes

Importing a @FrontMcp-decorated class starts an HTTP server at import time unless FRONTMCP_STDIO=1 is set before the import. For a hand-written stdio entry, keep the config object in its own module (as above) so no decorated class is evaluated. For built servers, use the --stdio runner (./dist/node/<name> --stdio) or a --target cli binary (<bin> --stdio) — both set the flag for you, so the decorated server connects over stdio and binds no port.

Instance Methods

getConfig()

Get the server configuration.

getConfig(): FrontMcpConfigType

getScopes()

Get all initialized scopes.

getScopes(): ScopeEntry[]

const instance = await FrontMcpInstance.createForGraph(config);
const scopes = instance.getScopes();

scopes.forEach(scope => {
  console.log('Scope ID:', scope.id);
  console.log('Tools:', scope.tools.getTools().map(t => t.name));
});

getPrimaryScope()

Get the scope that holds the server’s own apps. createDirect, createFetchHandler, runStdio and connect() serve this scope.

getPrimaryScope(): ScopeEntry | undefined

A standalone app, such as DashboardApp, gets a scope of its own that comes first in getScopes(), so the first scope is not always the server’s. When no app shares the server’s scope (every app is standalone, or splitByApp), this is the first scope.

Up to 1.8.2, those entry points served the first scope: with DashboardApp in apps they served the dashboard’s tools instead of the server’s.

start()

Start the HTTP server (called internally by bootstrap).

start(): Promise<void>

Initialization Sequence

Constructor
  ↓ sets this.ready = this.initialize()
initialize()
  ↓
1. Initialize ProviderRegistry (global providers)
2. Initialize LoggerRegistry (depends on providers)
3. Initialize ScopeRegistry (creates Scope instances)
  ↓
ready Promise resolves

Usage Examples

Development Server

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

async function main() {
  await FrontMcpInstance.bootstrap(config);
  console.log('Server started');
}

main().catch(console.error);

Serverless (Vercel)

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

export default FrontMcpInstance.createHandler(config);

Testing

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

describe('MCP Server', () => {
  let server: DirectMcpServer;

  beforeAll(async () => {
    server = await FrontMcpInstance.createDirect(config);
  });

  afterAll(async () => {
    await server.dispose();
  });

  test('list tools', async () => {
    const tools = await server.listTools();
    expect(tools.length).toBeGreaterThan(0);
  });

  test('call tool', async () => {
    const result = await server.callTool('my_tool', { input: 'test' });
    expect(result).toBeDefined();
  });
});

Claude Desktop Integration

// claude_desktop_config.json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["dist/stdio.js"],
      "cwd": "/path/to/server"
    }
  }
}

// src/server-config.ts — a plain object; do NOT add @FrontMcp here
export const serverConfig = {
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
};

// src/stdio.ts — imports only the config, so nothing auto-starts an HTTP server
import { FrontMcpInstance } from '@frontmcp/sdk';
import { serverConfig } from './server-config';

await FrontMcpInstance.runStdio(serverConfig);

Keep serverConfig separate from your @FrontMcp-decorated main.ts. The decorator starts an HTTP server when its module is imported, so a stdio entry that imports the decorated class would bind a port alongside stdio. Importing just the config object avoids that.

@FrontMcp

Server decorator

Scope

Registry access

DirectClient

Programmatic access

Deployment

Deployment guides

Decorators

API

Errors

Class Definition

Properties

Factory Methods

bootstrap(options)

createHandler(options)

createFetchHandler(options)

createDirect(options)

createForGraph(options)

runStdio(optionsOrClass)

Instance Methods

getConfig()

getScopes()

getPrimaryScope()

start()

Initialization Sequence

Usage Examples

Development Server

Serverless (Vercel)

Testing

Claude Desktop Integration

@FrontMcp

Scope

DirectClient

Deployment

​Class Definition

​Properties

​Factory Methods

​bootstrap(options)

​createHandler(options)

​createFetchHandler(options)

​createDirect(options)

​createForGraph(options)

​runStdio(optionsOrClass)

​Instance Methods

​getConfig()

​getScopes()

​getPrimaryScope()

​start()

​Initialization Sequence

​Usage Examples

​Development Server

​Serverless (Vercel)

​Testing

​Claude Desktop Integration

​Related

@FrontMcp

Scope

DirectClient

Deployment

Class Definition

Properties

Factory Methods

bootstrap(options)

createHandler(options)

createFetchHandler(options)

createDirect(options)

createForGraph(options)

runStdio(optionsOrClass)

Instance Methods

getConfig()

getScopes()

getPrimaryScope()

start()

Initialization Sequence

Usage Examples

Development Server

Serverless (Vercel)

Testing

Claude Desktop Integration

Related