# How the Welcome Onboarding System Integrates with Different MCP Clients in DesktopCommanderMCP

> Learn how DesktopCommanderMCP's welcome onboarding system integrates with various MCP clients. Discover personalized onboarding flows triggered by client names, configuration flags, and A/B testing for a tailored user experience.

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

---

**The DesktopCommanderMCP server triggers a client-specific onboarding flow by passing the connecting client's name to `handleWelcomePageOnboarding()`, which uses persisted configuration flags and A/B testing to determine whether to open a tailored welcome page in the user's default browser.**

The DesktopCommanderMCP repository implements a sophisticated welcome onboarding system that adapts to different MCP (Multi-Client Platform) clients. When a new client connects to the server, the system identifies the specific client type and conditionally launches a browser-based welcome experience. This integration ensures that users receive contextual onboarding while allowing developers to track engagement across different client implementations.

## Triggering the Onboarding Flow from Client Connections

The integration begins when the server detects a new client connection. In [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) at approximately line 225, the server invokes the onboarding handler with the specific client identifier:

```typescript
// src/server.ts – called when a client connects
await handleWelcomePageOnboarding(currentClient.name);

```

The `currentClient.name` parameter provides the **MCP client identity** (such as "Claude Desktop" or other client identifiers) that flows through the entire onboarding pipeline. This client-aware architecture ensures that each integration receives tailored treatment and analytics attribution.

## Client-Aware Routing and UTM Tracking

The `handleWelcomePageOnboarding` function in [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) receives the client name and passes it to the browser launch utility for analytics segmentation. When the system decides to show the welcome page, it calls `openWelcomePage(clientName)`, which constructs a targeted URL:

```typescript
// src/utils/open-browser.ts – opens the welcome page in the user's default browser
export async function openWelcomePage(clientName?: string): Promise<void> {
  const url =
    'https://desktopcommander.app/welcome/' +
    (clientName ? `?utm_source=${encodeURIComponent(clientName)}` : '');
  await openBrowser(url);
}

```

This **UTM source parameter** allows the DesktopCommanderMCP team to segment traffic and conversion metrics by specific MCP client implementations, providing clear analytics on which clients drive the most engagement with the onboarding experience.

## Feature Flag Gating and A/B Test Logic

Before displaying the welcome page, the system implements sophisticated **feature flag gating** to support A/B testing. The onboarding utility waits for fresh feature flag data and checks whether the current user should see the page:

```typescript
// src/utils/welcome-onboarding.ts
const loadedFromCache = featureFlagManager.wasLoadedFromCache();
if (!loadedFromCache) await featureFlagManager.waitForFreshFlags();

const shouldShow = await hasFeature('showOnboardingPage');
capture('server_welcome_page_ab_decision', {
  variant: shouldShow ? 'treatment' : 'control',
  loaded_from_cache: loadedFromCache,
});

```

If the user falls into the *control* group, the system updates the configuration flags to skip onboarding without showing the page. This logic, implemented in [`src/utils/ab-test.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ab-test.ts), allows the team to gradually roll out the welcome experience or experiment with different onboarding strategies across different MCP client populations.

## Persisted State Management

The system uses `configManager` (defined in [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts)) to maintain two critical flags that prevent redundant onboarding displays:

- **`pendingWelcomeOnboarding`**: Set when the configuration file is first created, indicating a fresh installation that requires onboarding
- **`sawOnboardingPage`**: Set after the welcome page successfully opens, preventing repeat displays

The onboarding handler checks `pendingWelcomeOnboarding` immediately upon invocation. If the value is falsy, the function exits early, ensuring that existing users or those who have completed onboarding do not experience the flow again.

## Complete Onboarding Implementation

The full implementation in [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) coordinates these components to deliver a seamless client-specific experience:

```typescript
// src/utils/welcome-onboarding.ts
export async function handleWelcomePageOnboarding(clientName?: string): Promise<void> {
  const pending = await configManager.getValue('pendingWelcomeOnboarding');
  if (!pending) return;

  const loadedFromCache = featureFlagManager.wasLoadedFromCache();
  if (!loadedFromCache) await featureFlagManager.waitForFreshFlags();

  const shouldShow = await hasFeature('showOnboardingPage');
  capture('server_welcome_page_ab_decision', {
    variant: shouldShow ? 'treatment' : 'control',
    loaded_from_cache: loadedFromCache,
  });

  if (!shouldShow) {
    await configManager.setValue('sawOnboardingPage', false);
    await configManager.setValue('pendingWelcomeOnboarding', false);
    return;
  }

  const alreadyShown = await configManager.getValue('sawOnboardingPage');
  if (alreadyShown) return;

  try {
    await openWelcomePage(clientName);               // ← opens https://desktopcommander.app/welcome/?utm_source=…
    await configManager.setValue('sawOnboardingPage', true);
    await configManager.setValue('pendingWelcomeOnboarding', false);
    capture('server_welcome_page_opened', { success: true });
  } catch (e) {
    await configManager.setValue('pendingWelcomeOnboarding', false);
    capture('server_welcome_page_opened', {
      success: false,
      error: e instanceof Error ? e.message : String(e),
    });
  }
}

```

## Summary

- **Client Identification**: The system captures the MCP client name from `currentClient.name` in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) and passes it through the entire onboarding pipeline.
- **Conditional Display**: Feature flags in [`src/utils/ab-test.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ab-test.ts) enable A/B testing, allowing the team to control which users see the welcome page based on experimental cohorts.
- **Persistence Layer**: Configuration flags (`pendingWelcomeOnboarding` and `sawOnboardingPage`) in [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) ensure the experience only appears once per installation.
- **Analytics Integration**: The `utm_source` parameter tagged with the client name enables precise attribution of onboarding engagement to specific MCP client implementations.
- **Cross-Platform Browser Launch**: The `openBrowser` utility in [`src/utils/open-browser.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/open-browser.ts) handles opening the welcome URL in the default browser across different operating systems.

## Frequently Asked Questions

### How does DesktopCommanderMCP detect which MCP client is connecting?

The server detects the client identity through the `currentClient.name` property available when a connection is established. This value is passed directly to `handleWelcomePageOnboarding()` in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), allowing the system to track and customize the experience for each specific MCP client implementation.

### What prevents the welcome page from showing repeatedly?

Two persisted configuration flags in [`src/config-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/config-manager.ts) control the lifecycle of the onboarding experience. The `pendingWelcomeOnboarding` flag is checked at the start of the function, and if false, the process exits immediately. After successful display, `sawOnboardingPage` is set to true, creating a permanent record that prevents future invocations from opening the browser again.

### How does the A/B testing system work for the onboarding flow?

The system uses `featureFlagManager.waitForFreshFlags()` to ensure current experiment definitions are loaded, then calls `hasFeature('showOnboardingPage')` to determine the user's variant. Users in the treatment group see the welcome page, while control group users skip the visualization but still mark the onboarding as complete. This logic supports gradual rollouts and experimentation across different MCP client user bases.

### Can the welcome page URL be customized for different clients?

While the base URL (`https://desktopcommander.app/welcome/`) remains constant, the system appends a `utm_source` query parameter containing the specific client name. This allows analytics platforms to segment traffic by client type and enables the welcome page itself to potentially customize content based on the source parameter, though the core URL structure is standardized across all MCP client integrations.