Machine ID

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

Priority	Source	When Used
1	`MACHINE_ID` env var	Always (explicit override, highest priority)
2	`setMachineIdOverride()`	Programmatic override (testing, direct API)
3	`HOSTNAME` env var	Distributed mode (Kubernetes pod name)
4	`os.hostname()`	Distributed mode fallback
5	Random UUID	Serverless mode (ephemeral, per-invocation)
6	`.frontmcp/machine-id` file	Development only (persisted across restarts)
7	Random UUID	Production fallback

The .frontmcp/machine-id file is only read and written in standalone development (NODE_ENV !== 'production', no MACHINE_ID). It is created on the first getMachineId() call, in the background and without blocking startup, with the directory at mode 0700 and the file at 0600. It is never written in distributed (the ID comes from HOSTNAME / os.hostname()) or serverless mode. In production without an env var, a random UUID is generated on each startup, so session ownership does not survive a restart: set MACHINE_ID or run in distributed mode.

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

Variable	Purpose	Default
`MACHINE_ID`	Explicit machine ID override (highest priority)	---
`MACHINE_ID_PATH`	Custom path for the machine-id file	`.frontmcp/machine-id`
`FRONTMCP_DEPLOYMENT_MODE`	Affects resolution strategy (`distributed` / `serverless` / `standalone`)	`standalone`
`HOSTNAME`	Kubernetes 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

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Resolution Order

Usage

Distributed Deployment

Direct API

Environment Variables

High Availability

Runtime Modes

Direct Client

​Resolution Order

​Usage

​Distributed Deployment

​Direct API

​Environment Variables

​Related

High Availability

Runtime Modes

Direct Client

Resolution Order

Usage

Distributed Deployment

Direct API

Environment Variables

Related