> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FrontMcpServer

> FrontMcpServer manages the HTTP server interface for FrontMCP. It supports multiple host adapters (Express, Fastify, etc.) and both server and serverless deployments.

## Class Definition

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
export class FrontMcpServerInstance extends FrontMcpServer {
  config: HttpOptions;
  host: HostServerAdapter;
}
```

## Properties

| Property | Type                | Description                  |
| -------- | ------------------- | ---------------------------- |
| `config` | `HttpOptions`       | HTTP configuration           |
| `host`   | `HostServerAdapter` | Host adapter (Express, etc.) |

## Methods

### registerMiddleware(entryPath, handler)

Register middleware at a specific entry path.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
registerMiddleware(entryPath: string, handler: ServerRequestHandler): void
```

### registerRoute(method, path, handler)

Register an HTTP route.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
registerRoute(
  method: HttpMethod,
  path: string,
  handler: ServerRequestHandler
): void
```

### prepare()

Prepare routes without starting the server.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
prepare(): void
```

* Registers `/health` endpoint automatically
* Prepares all configured routes
* Call before `getHandler()` for serverless

### getHandler()

Get the underlying HTTP handler for serverless export.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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).

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
start(): Promise<void>
```

## HttpOptions

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@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:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { FrontMcpInstance } from '@frontmcp/sdk';
import config from './server';

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

### Manual Server Access

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// 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

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@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:

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# 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
```

| Endpoint   | Purpose                                | I/O  | Runtime                  |
| ---------- | -------------------------------------- | ---- | ------------------------ |
| `/healthz` | Liveness probe                         | None | All                      |
| `/readyz`  | Readiness probe with dependency checks | Yes  | Node, Bun, Deno, Browser |
| `/health`  | Legacy alias for `/healthz`            | None | All                      |

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

<Card title="Health Checks Guide" icon="heart-pulse" href="/frontmcp/deployment/health-checks">
  Full configuration, custom probes, Kubernetes & Docker examples
</Card>

## Related

<CardGroup cols={2}>
  <Card title="FrontMcpInstance" icon="server" href="/frontmcp/sdk-reference/core/frontmcp-instance">
    Server bootstrap
  </Card>

  <Card title="@FrontMcp" icon="at" href="/frontmcp/sdk-reference/decorators/frontmcp">
    Server configuration
  </Card>

  <Card title="Serverless Deployment" icon="cloud" href="/frontmcp/deployment/serverless">
    Serverless guide
  </Card>

  <Card title="Production Build" icon="rocket" href="/frontmcp/deployment/production-build">
    Production deployment
  </Card>
</CardGroup>