Skip to main content

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.

Every FrontMCP instance has a stable machine ID used for session ownership, HA heartbeats, load balancer affinity, and distributed tracing. The ID is resolved differently based on deployment mode.

​
Resolution Order

PrioritySourceWhen Used
1MACHINE_ID env varAlways (explicit override, highest priority)
2setMachineIdOverride()Programmatic override (testing, direct API)
3HOSTNAME env varDistributed mode (Kubernetes pod name)
4os.hostname()Distributed mode fallback
5Random UUIDServerless mode (ephemeral, per-invocation)
6.frontmcp/machine-id fileDevelopment only (persisted across restarts)
7Random UUIDProduction fallback
The .frontmcp/machine-id file is only created in development (NODE_ENV !== 'production'). In production without an env var, a random UUID is generated on each startup.

​
Usage

import { getMachineId, setMachineIdOverride } from '@frontmcp/utils';

// Read the current machine ID
const id = getMachineId(); // e.g., "mcp-server-7b8f9-abc12"

// Override for testing
setMachineIdOverride('test-stable-id');
expect(getMachineId()).toBe('test-stable-id');

// Clear override
setMachineIdOverride(undefined);

​
Distributed Deployment

In Kubernetes, each pod automatically gets its machine ID from the HOSTNAME environment variable, which Kubernetes sets to the pod name (e.g., mcp-server-7b8f9-abc12). This ensures:
  • Session affinity: the __frontmcp_node cookie and X-FrontMCP-Machine-Id header are tied to the actual pod
  • Heartbeat identity: each pod’s heartbeat key (mcp:ha:heartbeat:{nodeId}) maps to its pod name
  • Takeover correctness: session ownership references the real pod, not a random ID
# Kubernetes sets HOSTNAME automatically --- no config needed
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: mcp-server
          env:
            - name: FRONTMCP_DEPLOYMENT_MODE
              value: distributed
            # HOSTNAME is set by Kubernetes to the pod name

​
Direct API

The create() factory function accepts a machineId option for stable identity in tests and embedded usage: 
import { create } from '@frontmcp/sdk';

const server = await create({
  info: { name: 'test-server', version: '1.0.0' },
  tools: [MyTool],
  machineId: 'stable-test-id', // Override machine ID for this instance
});
This calls setMachineIdOverride() internally before initializing the server.

​
Environment Variables

VariablePurposeDefault
MACHINE_IDExplicit machine ID override (highest priority)---
MACHINE_ID_PATHCustom path for the machine-id file.frontmcp/machine-id
FRONTMCP_DEPLOYMENT_MODEAffects resolution strategy (distributed / serverless / standalone)standalone
HOSTNAMEKubernetes pod name (used in distributed mode)Set by K8s
For local development with multiple instances, set MACHINE_ID to different values for each process to simulate multi-pod behavior.

High Availability

Multi-pod deployment with session failover

Runtime Modes

Standalone, distributed, and serverless modes

Direct Client

In-process MCP server for testing and embedding