Installation

This guide covers installing and configuring the B2C DX MCP Server for various MCP clients.

Prerequisites

• Node.js 22.0.0 or higher
• A B2C Commerce project (for project-specific toolsets)
• MCP client (Claude Code, Cursor, GitHub Copilot, or compatible client)

Note: For Figma-to-component tools, you also need an external Figma MCP server enabled. See Figma-to-Component Tools Setup for details.

Installation Method

The MCP server is installed via npx, which downloads and runs the latest version on demand.

Project Directory

The server automatically detects your project location to enable:

1. Auto-discovery - Detects your project type and enables appropriate toolsets
2. Configuration loading - Reads dw.json from your project root for B2C credentials
3. Scaffolding - Creates new files in the correct location based on your project structure

Detection methods:

• Cursor (project-level): Automatically detected from the MCP config file location
• Cursor (user-level): Requires --project-directory "${workspaceFolder}" in the args array
• Claude Code: Automatically detected from the current working directory (cd into project root before installation)
• GitHub Copilot: Automatically detected from the workspace location

Project Type Detection

The server automatically detects your project type:

Project Type	Detection Criteria	Enabled Toolsets
PWA Kit v3	@salesforce/pwa-kit-*, @salesforce/retail-react-app, or ccExtensibility in package.json	PWAV3, MRT, SCAPI
Storefront Next	Root or workspace package has @salesforce/storefront-next* dependency, or package name starting with storefront-next	STOREFRONTNEXT, MRT, CARTRIDGES, SCAPI
Cartridges	.project file in cartridge directory	CARTRIDGES, SCAPI
No project detected	No B2C markers found	SCAPI (base toolset only)

Hybrid projects (e.g., cartridges + PWA Kit) get combined toolsets.

Claude Code

Claude Code supports MCP servers via CLI installation:

Project Scope (Recommended)

cd /path/to/your/project
claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools

User Scope

claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools

See the Claude Code MCP documentation for details on scope options and configuration.

Cursor

Cursor supports project-level configuration via .cursor/mcp.json in your project root.

Project-Level Configuration (Recommended)

Project-level configuration automatically detects your project location and can be shared with your team via version control.

1. Create or edit .cursor/mcp.json in your project root
2. Add the following configuration:

{
  "mcpServers": {
    "b2c-dx-mcp": {
      "command": "npx",
      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
    }
  }
}

3. Restart Cursor or reload the MCP server

With project-level configuration, the server automatically detects your project location without requiring the --project-directory flag. See the Cursor MCP documentation for details.

Quick Install (User-Level)

Alternatively, use the "Add to Cursor" link to add to user-level configuration:

Add to Cursor

Manual Configuration (Windows or if link doesn't work):

1. Open or create ~/.cursor/mcp.json (on Windows: C:\Users\<your-username>\.cursor\mcp.json)
2. Add the following configuration:

{
  "mcpServers": {
    "b2c-dx-mcp": {
      "command": "npx",
      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--project-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
    }
  }
}

Note: Cursor uses "mcpServers" as the top-level key. For GitHub Copilot/VS Code, use "servers" instead (see GitHub Copilot section). The ${workspaceFolder} variable automatically expands to your current workspace, so no manual updates are needed when switching projects.

GitHub Copilot

GitHub Copilot supports MCP servers via configuration in your workspace. See the GitHub Copilot MCP documentation for setup instructions.

Copilot supports project-level configuration. Create the MCP config file in your workspace (.vscode/mcp.json):

{
  "servers": {
    "b2c-dx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
    }
  },
  "inputs": []
}

Note: GitHub Copilot/VS Code uses "servers" (not "mcpServers") and requires "type": "stdio" for stdio-based servers. The "inputs" array is optional but included for consistency with VS Code's format.

With project-level configuration, the server automatically detects your project location.

Troubleshooting

Server Not Starting

• Verify Node.js version: node --version (must be 22.0.0+)
• Check that npx is available and working

"Could not determine executable to run" Error (Windows)

This error occurs when npx uses a cached broken version (0.0.1) instead of the latest version. npx's cache-first behavior can reuse an older cached version even when newer versions are available.

Solution:

1. Update your MCP configuration to use @latest:

   {
     "mcpServers": {
       "b2c-dx-mcp": {
         "command": "npx",
         "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
       }
     }
   }

2. Clear the npx cache if the issue persists:

   npm cache clean --force

Prevention: Always use @latest in your MCP configuration to ensure npx fetches the latest version from the registry instead of using cached versions.

Tools Not Available

• Ensure --allow-non-ga-tools flag is included (required for preview tools)
• Verify project type detection by checking your package.json or project structure
• If using user-level Cursor configuration, ensure --project-directory "${workspaceFolder}" is included

Configuration Not Loading

• Ensure dw.json exists in your project root
• Verify you're using project-level configuration (recommended)
• Check file permissions on dw.json

Next Steps

• Configuration - Configure credentials, flags, and toolset selection
• Toolsets & Tools - Explore available toolsets and tools
• MCP Server Overview - Learn more about the MCP server