---
title: "FrontMcpInstance"
description: "FrontMcpInstance is the main entry point for creating and managing FrontMCP servers. It provides multiple factory methods for different deployment scenarios."
icon: "server"
keywords: ['frontmcp', 'mcp', 'model context protocol', 'sdk', 'reference', 'api', 'core api', 'instance', 'typescript']
---

## Class Definition

```typescript
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.

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

Best for: Standalone HTTP server deployments.

```typescript
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.

```typescript
static async createHandler(options: FrontMcpConfigType): Promise<unknown>
```

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

```typescript
// 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.

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

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

```typescript
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.

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

Best for: Graph visualization, introspection, analysis.

```typescript
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.

```typescript
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()`.

```typescript
// 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
```

<Warning>
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.
</Warning>

## Instance Methods

### getConfig()

Get the server configuration.

```typescript
getConfig(): FrontMcpConfigType
```

### getScopes()

Get all initialized scopes.

```typescript
getScopes(): ScopeEntry[]
```

```typescript
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).

```typescript
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

```typescript
// 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)

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

export default FrontMcpInstance.createHandler(config);
```

### Testing

```typescript
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

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

```typescript
// 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],
};
```

```typescript
// 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);
```

<Tip>
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.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="@FrontMcp" icon="at" href="/frontmcp/sdk-reference/decorators/frontmcp">
    Server decorator
  </Card>
  <Card title="Scope" icon="layer-group" href="/frontmcp/sdk-reference/core/scope">
    Registry access
  </Card>
  <Card title="DirectClient" icon="plug" href="/frontmcp/sdk-reference/core/direct-client">
    Programmatic access
  </Card>
  <Card title="Deployment" icon="rocket" href="/frontmcp/deployment/production-build">
    Deployment guides
  </Card>
</CardGroup>
