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: 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);

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));
});

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)

createDirect(options)

createForGraph(options)

runStdio(optionsOrClass)

Instance Methods

getConfig()

getScopes()

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)

​createDirect(options)

​createForGraph(options)

​runStdio(optionsOrClass)

​Instance Methods

​getConfig()

​getScopes()

​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)

createDirect(options)

createForGraph(options)

runStdio(optionsOrClass)

Instance Methods

getConfig()

getScopes()

start()

Initialization Sequence

Usage Examples

Development Server

Serverless (Vercel)

Testing

Claude Desktop Integration

Related