How to Customize or Disable the Onboarding Flow in Desktop Commander MCP

Pass the --no-onboarding flag when launching the MCP server to completely suppress all onboarding prompts, or modify configuration files and source components to customize the experience.

Desktop Commander MCP displays an onboarding experience to new users during their first session. You can disable this flow entirely using command-line flags or tailor it by editing specific source files in the wonderwhy-er/DesktopCommanderMCP repository. This guide explains the exact mechanisms that control onboarding behavior.

How the --no-onboarding Flag Works

The entry point in src/index.ts parses command-line arguments and sets a global variable that downstream components check before displaying onboarding elements.

At lines 44-51, the server detects the flag:

const DISABLE_ONBOARDING = process.argv.includes('--no-onboarding');
if (DISABLE_ONBOARDING) { logToStderr('info', 'Onboarding disabled via --no-onboarding flag'); }
(global as any).disableOnboarding = DISABLE_ONBOARDING;

This global flag propagates to two critical files. In src/utils/usageTracker.ts (lines 45-48), the system checks the flag and returns early:

if ((global as any).disableOnboarding) {
  return false; // skip onboarding
}

Similarly, src/utils/welcome-onboarding.ts (lines 45-52) reads this global setting to prevent the browser tab from opening.

Running Desktop Commander MCP Without Onboarding

To launch the server and bypass all onboarding prompts, append the flag to your start command:

# Suppress onboarding completely

desktop-commander-mcp --no-onboarding

When present, this flag overrides both feature-flag settings and local configuration, ensuring no welcome pages or injection prompts appear.

Customizing the Onboarding Experience

To modify rather than disable the flow, edit these specific components:

Feature Flag and Configuration Controls

The shouldShowOnboarding() function in src/utils/usageTracker.ts checks multiple gatekeepers:

• Remote feature flags: featureFlagManager.get('onboarding_injection') enables or disables onboarding globally.
• Local configuration: configManager.getValue('onboarding_injection') reads user-specific settings from config.json.

Retry Logic and Attempt Limits

Lines 78-89 of src/utils/usageTracker.ts contain the shouldShowOnboarding() logic that controls how many times the prompt appears and the delay between attempts. Edit these lines to change the frequency of onboarding injections.

Welcome Page Content and A/B Testing

The src/utils/welcome-onboarding.ts file uses hasFeature('showOnboardingPage') to determine whether to open the browser. To force the welcome page for all users, modify the A/B test assignment:

// Force treatment for every new install
const shouldShow = true;   // ← replace the call to hasFeature(...)

The actual HTML content rendered in the browser is controlled by src/utils/open-browser.ts.

Disabling Onboarding via Configuration File

As an alternative to the command-line flag, add this entry to your config.json:

{
  "onboarding_injection": false
}

The configuration manager reads this value in src/utils/usageTracker.ts, causing shouldShowOnboarding() to return false even without the --no-onboarding flag.

Summary

• Pass --no-onboarding when starting the server to completely disable the flow via the global flag set in src/index.ts.
• Edit src/utils/usageTracker.ts to modify retry logic, attempt limits, and feature-flag checks.
• Modify src/utils/welcome-onboarding.ts to control the welcome page A/B test and browser launch behavior.
• Use config.json with "onboarding_injection": false for a persistent disable without command-line flags.
• Update src/utils/open-browser.ts to change the actual HTML content shown to users.

Frequently Asked Questions

Where is the --no-onboarding flag parsed in the source code?

The flag is parsed in src/index.ts at lines 44-51 using process.argv.includes('--no-onboarding'). When detected, it sets (global as any).disableOnboarding = true, which src/utils/usageTracker.ts and src/utils/welcome-onboarding.ts check before showing any onboarding elements.

Can I disable onboarding without using the command-line flag?

Yes. Set "onboarding_injection": false in your config.json file. The configManager.getValue('onboarding_injection') call in src/utils/usageTracker.ts will read this setting and prevent onboarding from displaying.

How do I change how many times the onboarding prompt appears?

Edit the shouldShowOnboarding() function in src/utils/usageTracker.ts around lines 78-89. This function contains the logic for attempt counting and delay intervals between onboarding prompts.

What file controls the welcome page content?

The HTML content for the welcome page is managed in src/utils/open-browser.ts, which is called from the openWelcomePage function in src/utils/welcome-onboarding.ts. Edit this file to customize the visual presentation shown to new users.

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