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

# Machine ID

> Deployment-aware machine identity for session affinity, HA takeover, and distributed tracing

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 |

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

## Usage

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

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

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

<Tip>
  For local development with multiple instances, set `MACHINE_ID` to different values for each process to simulate multi-pod behavior.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="High Availability" icon="server" href="/frontmcp/deployment/high-availability">
    Multi-pod deployment with session failover
  </Card>

  <Card title="Runtime Modes" icon="layer-group" href="/frontmcp/deployment/runtime-modes">
    Standalone, distributed, and serverless modes
  </Card>

  <Card title="Direct Client" icon="plug" href="/frontmcp/deployment/direct-client">
    In-process MCP server for testing and embedding
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.