# How Feature Flags Dynamically Control Server Behavior in DesktopCommanderMCP

> Learn how feature flags in DesktopCommanderMCP dynamically control server behavior. Enable runtime toggling of features without server restarts via cached remote configuration.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-14

---

**Feature flags in DesktopCommanderMCP enable runtime toggling of functionality via a singleton manager that caches remote configuration locally and evaluates flags on every request without requiring server restarts.**

DesktopCommanderMCP implements a lightweight feature flag system to dynamically control server behavior without code changes or redeployments. The architecture uses a centralized singleton defined in [`src/utils/feature-flags.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/feature-flags.ts) that loads JSON configuration from a remote service while maintaining a local cache for resilience. This implementation allows the server to adjust functionality instantly based on flag states evaluated at runtime.

## The Feature Flag Architecture

### Singleton Pattern and Initialization

The feature flag system initializes in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) as a non-blocking startup task. The `FeatureFlags` singleton loads configuration asynchronously, ensuring the server accepts requests immediately while flags populate in the background. This design prevents network latency from delaying server availability.

### Remote Configuration and Local Caching

The system fetches a JSON document from a remote configuration service containing key-value pairs like `{ "enableUsageTracking": true, "remoteKillSwitch": false }`. These values are written to [`.feature-flags.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.feature-flags.json) on disk. On subsequent starts, the server loads cached flags instantly if the network is unavailable, guaranteeing continuous operation with known configuration states.

## Runtime Evaluation and Dynamic Control

### The `isEnabled` API

Core modules query flag states through `FeatureFlags.isEnabled(flagName)`, a synchronous check performed at execution time. Because flags are evaluated during every guarded code path execution, remote changes take effect immediately without restarting the server.

### Practical Implementation Examples

Developers guard optional functionality using the singleton API:

```typescript
import { FeatureFlags } from '@/utils/feature-flags';

// Conditional telemetry emission
if (FeatureFlags.isEnabled('enableUsageTracking')) {
  sendTelemetry(data);
}

// Emergency kill switch for critical operations
if (!FeatureFlags.isEnabled('remoteKillSwitch')) {
  performCriticalUpdate();
}

```

## Use Cases in DesktopCommanderMCP

### Usage Tracking Controls

In [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts), the system checks the `enableUsageTracking` flag before emitting telemetry data. It also respects `remoteKillSwitch` to disable all reporting dynamically, protecting against runaway processes or compliance issues.

### Onboarding Flow Management

The [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) module waits for the flag cache to load and conditionally renders the welcome UI. If a flag disables onboarding for specific user cohorts, the server skips the presentation logic entirely.

### A/B Testing Integration

The [`src/utils/ab-test.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ab-test.ts) utility reads experiment definitions from the same flag payload, enabling weighted rollouts of new UI variants. The `getExperimentVariant` method returns assignment values based on remote configuration:

```typescript
const variant = FeatureFlags.getExperimentVariant('newSidebar');
if (variant === 'control') {
  renderOldSidebar();
} else {
  renderNewSidebar();
}

```

## Summary

- The `FeatureFlags` singleton in [`src/utils/feature-flags.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/feature-flags.ts) manages remote configuration and local caching to [`.feature-flags.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.feature-flags.json)
- Runtime checks via `isEnabled()` and `getExperimentVariant()` allow immediate behavior changes without server restarts
- Usage tracking in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) respects kill switches for safe telemetry control
- Onboarding flows in [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) conditionally execute based on flag states
- A/B testing infrastructure in [`src/utils/ab-test.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ab-test.ts) leverages the same flag system for dynamic experiment allocation

## Frequently Asked Questions

### How do feature flags load without blocking server startup?

The initialization in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) creates the `FeatureFlags` singleton asynchronously, allowing the server to boot and accept requests while configuration loads in the background from the remote service.

### Where are feature flags cached locally?

Flags are persisted to [`.feature-flags.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.feature-flags.json) on disk, enabling the server to load the last known configuration instantly during startup if the remote configuration service is unreachable.

### Can feature flags change behavior without restarting the server?

Yes, because `FeatureFlags.isEnabled()` evaluates the current flag state on every invocation, updates to the remote configuration apply immediately to subsequent requests and operations without requiring a restart.

### What happens if the remote configuration service is unavailable?

The server falls back to the locally cached [`.feature-flags.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/.feature-flags.json) file, ensuring continuous operation with previously loaded flag values while attempting to refresh the configuration in the background.