Skip to main content

​
Class Definition

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

​
Properties

PropertyTypeDescription
configFrontMcpConfigTypeParsed server configuration
readyPromise<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