# Desktop Commander MCP Onboarding System: How It Detects User Experience Levels

> Learn how Desktop Commander MCP's onboarding system detects user experience levels by tracking persistent state and disabling prompts after 10 tool calls.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Desktop Commander MCP uses a feature-flagged onboarding system that detects user experience levels through persistent state tracking and automatically disables prompts after 10 total tool calls.**

The Desktop Commander MCP server implements an intelligent onboarding flow that adapts to user behavior. This article examines how the system determines when to display onboarding prompts, what triggers experience-level detection, and where these mechanisms live in the source code.

## Core Components of the Onboarding System

The onboarding architecture consists of three interconnected components designed to minimize friction for experienced users while guiding newcomers.

### Feature-Flag Gate

All onboarding logic begins with a remote feature flag. In [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts), the `shouldShowOnboarding()` method first checks `onboarding_injection`:

```typescript
const onboardingEnabled = featureFlagManager.get('onboarding_injection', false);
if (!onboardingEnabled) return false;

```

This gate (lines 424–435) allows maintainers to disable onboarding globally without deploying new code.

### Persistent Onboarding State

The system tracks interaction history through `onboardingState`, stored in the config store:

```typescript
interface OnboardingState {
  promptsUsed: number;
  attemptsShown: number;
  lastShownAt: number;
}

```

Located at lines 32–36 in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts), this state persists across sessions and prevents repetitive prompts.

### Usage-Based Heuristics

The critical experience threshold is enforced through global usage statistics. When `totalToolCalls` reaches **10 or more**, onboarding ceases automatically:

```typescript
// Simplified from lines 70–73, src/utils/usageTracker.ts
if (stats.totalToolCalls >= 10) {
  return false; // User no longer qualifies as "new"
}

```

## How Onboarding Detection Works Step-by-Step

### Step 1: Client Connection Triggers Evaluation

When a client connects to the MCP server, [`server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/server.ts) initiates the onboarding check:

```typescript
// src/server.ts, lines 21–27
if (isWelcomePageEligibleClient) {
    await handleWelcomePageOnboarding(currentClient.name);
}

```

This A/B-tested welcome page runs before any tool execution.

### Step 2: Feature Flag Verification

The `UsageTracker` evaluates three conditions in sequence:

1. **Remote flag** – `onboarding_injection` must be enabled
2. **Local config** – User can override via `"onboarding_injection": false`
3. **CLI argument** – `--no-onboarding` sets `disableOnboarding` globally

Lines 440–448 in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) implement these fallbacks:

```typescript
// Local override from config store
const localOverride = config.get('onboarding_injection');
if (localOverride === false) return false;

// CLI argument handling
if (global.disableOnboarding) return false;

```

### Step 3: Experience Level Classification

The system categorizes users through two metrics:

| Metric | Threshold | Classification |
|--------|-----------|----------------|
| `totalToolCalls` | < 10 | New user – onboarding eligible |
| `totalToolCalls` | ≥ 10 | Experienced user – onboarding suppressed |
| `promptsUsed` | > 0 | Engaged user – track feature adoption |
| `attemptsShown` | Any | Frequency cap enforcement |

## New User vs. Experienced User Detection

### New User Path

Users with fewer than 10 tool calls encounter:

- The 5-option onboarding menu on first eligible interaction
- Persistent tracking of which prompts they've actually used (`promptsUsed`)
- Timestamp recording (`lastShownAt`) for frequency limiting

### Experienced User Bypass

Once `totalToolCalls >= 10`, the early-return in `shouldShowOnboarding()` prevents any further display:

```typescript
// src/utils/usageTracker.ts, the experience gate
const stats = this.getGlobalStats();
if (stats.totalToolCalls >= EXPERIENCED_USER_THRESHOLD) {
  return false;
}

```

This threshold is hardcoded but evaluated dynamically—users automatically graduate without manual intervention.

## Configuration and Overrides

Administrators and users can control onboarding through multiple mechanisms:

- **Remote management** – Feature flag service controls `onboarding_injection`
- **Config file** – Set `"onboarding_injection": false` in Desktop Commander settings
- **Process arguments** – Launch with `--no-onboarding` for CI/automated environments

These layers operate as an OR-gate: any disable signal prevents onboarding.

## Summary

- Desktop Commander MCP detects user experience levels through **`totalToolCalls` thresholding** (≥10 calls = experienced)
- The onboarding system lives primarily in **[`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts)** with initialization in **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)**
- Three override mechanisms exist: **remote flag, local config, and CLI argument**
- Persistent state tracking prevents repetitive prompts while measuring feature adoption via `promptsUsed`

## Frequently Asked Questions

### What triggers the onboarding flow in Desktop Commander MCP?

The onboarding flow triggers when a client connects to the server and passes eligibility checks in [`server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/server.ts). The `handleWelcomePageOnboarding()` function runs for A/B-tested clients, provided the feature flag is enabled and the user has fewer than 10 total tool calls.

### Can I disable onboarding without modifying code?

Yes. Desktop Commander MCP supports three disable methods: set `"onboarding_injection": false` in your configuration file, launch the process with `--no-onboarding`, or wait for the maintainers to disable the remote `onboarding_injection` flag.

### Where is the 10-tool-call threshold defined?

The experienced-user threshold of 10 tool calls is implemented in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) around lines 70–73. The `getGlobalStats()` function retrieves `totalToolCalls`, and the comparison against this constant determines onboarding eligibility.

### How does the system remember I've seen onboarding before?

Onboarding state persists through the `onboardingState` object stored in the config store. It tracks `attemptsShown` (how many times displayed), `promptsUsed` (engagement metrics), and `lastShownAt` (timestamp for rate limiting) across all sessions.