How the Onboarding System in Desktop Commander MCP Works: Complete Technical Guide

Desktop Commander MCP uses a dual-flag eligibility system to distinguish new from experienced users, injecting welcome messages only during the first launch through A/B-tested flows controlled by welcomeOnboardingEligible and pendingWelcomeOnboarding flags in the config store.

The Desktop Commander MCP repository implements a sophisticated onboarding system that determines exactly when to display welcome guidance to new users while maintaining a frictionless experience for veterans. This technical deep dive examines how the codebase differentiates between fresh installations and returning users through persistent state flags, feature flags, and strategic injection points in the server lifecycle.

New vs. Experienced User Detection

The onboarding system relies on two distinct boolean flags stored in the configuration manager to classify users.

Eligibility Flags and First-Run Detection

When the configuration file is created for the first time, the system automatically sets welcomeOnboardingEligible to true. This flag acts as a permanent marker indicating a brand-new installation. Simultaneously, the pendingWelcomeOnboarding flag is set to true, creating a pending state that survives process restarts until a decision is made.

In src/utils/welcome-onboarding.ts, the eligibility check occurs at lines 41-45, where the code verifies welcomeOnboardingEligible is present. The pending status is validated at lines 48-53, ensuring the onboarding request remains active across server restarts until the user either sees the welcome page or is assigned to the control group.

Experienced users are identified by the absence of the eligibility flag (indicating an older configuration) or by having the pending flag cleared. Once pendingWelcomeOnboarding is set to false, the user will never trigger the onboarding flow again, regardless of subsequent restarts.

The Onboarding Execution Flow

The onboarding message injection happens during the server initialization sequence, seamlessly integrating with the LLM response stream.

Server Startup Injection Point

In src/server.ts around line 1565, the server queries the usage tracker to determine if onboarding should trigger:

const onboardingResult = await usageTracker.getOnboardingMessage();

If the result indicates onboarding is required, the system injects the welcome message into the LLM response content at lines 1586-1592. This injection point ensures the user receives contextual guidance within their first interaction without requiring a separate modal or popup window.

Welcome Page Handler Logic

The core onboarding logic resides in src/utils/welcome-onboarding.ts. When the server detects a pending onboarding state, it delegates to this utility to determine whether to display the welcome page or skip it based on A/B test assignments and client exclusions.

A/B Testing and Variant Assignment

Desktop Commander MCP implements controlled experiments to measure onboarding effectiveness through the showOnboardingPage feature flag.

Treatment vs. Control Groups

The variant assignment occurs through hasFeature('showOnboardingPage') evaluated at lines 80-82 in welcome-onboarding.ts.

Treatment: Users in the treatment group trigger openWelcomePage() (lines 103-107), which displays the welcome interface and immediately updates the persistence layer by setting sawOnboardingPage to true and clearing pendingWelcomeOnboarding.

Control: Users assigned to the control group bypass the welcome page. The system clears the pendingWelcomeOnboarding flag and records the decision via the capture() helper at lines 84-88 and 89-95, ensuring accurate analytics tracking for conversion rate analysis.

Both branches utilize the capture() analytics helper to emit telemetry events, enabling the team to measure engagement differences between users who see the onboarding versus those who proceed directly to functionality.

Configuration and Exclusions

The system provides multiple mechanisms to bypass onboarding for specific deployment scenarios or client types.

Client-Specific Exclusions

Certain client implementations (such as custom UI wrappers) can be excluded from the onboarding flow via the welcome_page_excluded_clients feature flag. The helper function isWelcomePageClientExcluded() at lines 19-29 in welcome-onboarding.ts checks the client name against this exclusion list.

If a client matches the exclusion criteria, the system immediately calls skipWelcomePageOnboarding() to clear the pending flag without displaying any welcome content, preventing redundant guidance in embedded or white-label implementations.

Command-Line Overrides

Users can suppress the entire onboarding system by launching the CLI with the --no-onboarding flag. In src/index.ts at lines 44-50, the argument parser detects this flag and sets the DISABLE_ONBOARDING environment variable, which short-circuits all subsequent onboarding checks regardless of persistence state.

# Launch Desktop Commander MCP without onboarding

desktop-commander --no-onboarding

State Persistence Model

All onboarding-related state lives in a JSON-based configuration store accessed through the config manager.

Config Store Schema

The following keys control the onboarding lifecycle:

Key	Purpose
welcomeOnboardingEligible	Permanent marker set only when the config file is first created
pendingWelcomeOnboarding	Transient state indicating an onboarding decision is pending
sawOnboardingPage	Confirmation that the welcome page was displayed
onboardingState	Granular tracking used by usageTracker for attempt counts and timestamps

These values are accessed throughout the codebase via configManager.getValue() and configManager.setValue(). The usageTracker module (in src/utils/usageTracker.ts) maintains additional metadata including attempt counters, last-shown timestamps, and prompt utilization metrics to support sophisticated nudging strategies beyond the initial welcome flow.

Code Example: Client Exclusion Check

// src/utils/welcome-onboarding.ts
if (isWelcomePageClientExcluded(clientName)) {
  await skipWelcomePageOnboarding();   // clears pending flag
  return;
}

Summary

• Dual-flag detection distinguishes new installations (welcomeOnboardingEligible) from decisions-in-progress (pendingWelcomeOnboarding), ensuring returning users never see repeated onboarding.
• A/B testing via the showOnboardingPage feature flag allows the team to measure conversion rates between treatment and control groups.
• Strategic injection occurs in src/server.ts through usageTracker.getOnboardingMessage(), embedding guidance directly into the LLM response stream.
• Flexible exclusions support both client-specific blocklists and CLI overrides via --no-onboarding.
• Persistent state stored in the JSON config manager ensures onboarding decisions survive process restarts and respect user history.

Frequently Asked Questions

How does Desktop Commander MCP determine if I am a new or experienced user?

The system checks for the presence of welcomeOnboardingEligible in your configuration file. This flag is only written when the config file is created for the first time. If you lack this flag entirely (indicating an older installation) or if your pendingWelcomeOnboarding flag has been cleared to false, the system classifies you as an experienced user and skips the welcome flow automatically.

Can I disable the onboarding system without modifying configuration files?

Yes. Launch the application with the --no-onboarding command-line argument. This sets the DISABLE_ONBOARDING environment variable early in the startup sequence (handled in src/index.ts lines 44-50), which bypasses all eligibility checks and prevents any onboarding messages from being injected into your session.

What happens if my MCP client is on the exclusion list?

If your client name matches the welcome_page_excluded_clients feature flag list, the function isWelcomePageClientExcluded() returns true at lines 19-29 in welcome-onboarding.ts. The system then calls skipWelcomePageOnboarding() to clear the pending flag immediately, allowing you to proceed with normal operation without seeing the welcome page.

Where is the onboarding state stored, and can I reset it manually?

All state persists in the JSON configuration store managed by configManager. Key values include welcomeOnboardingEligible, pendingWelcomeOnboarding, and sawOnboardingPage. You can manually reset your onboarding status by clearing these keys from the configuration file, though modifying welcomeOnboardingEligible specifically will re-qualify you as a "new" user on the next restart.

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