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

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, the shouldShowOnboarding() method first checks onboarding_injection:

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:

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

Located at lines 32–36 in 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:

// 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 initiates the onboarding check:

// 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 implement these fallbacks:

// 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:

// 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 with initialization in 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}