Configuration

The server discovers credentials in this priority order:

1. --dw-json /path/to/dw.json
2. Environment variables (SFCC_HOSTNAME, SFCC_USERNAME, SFCC_PASSWORD, SFCC_CLIENT_ID, SFCC_CLIENT_SECRET)
3. Workspace auto-discovery (VS Code workspace root containing a dw.json)

Environment variables example:

export SFCC_HOSTNAME="your-instance.sandbox.us01.dx.commercecloud.salesforce.com"
export SFCC_USERNAME="your-username"
export SFCC_PASSWORD="your-password"
export SFCC_CLIENT_ID="your-client-id"
export SFCC_CLIENT_SECRET="your-client-secret"

Workspace roots auto-discovery

Auto-discovery happens after the MCP client finishes initializing. The server requests workspace roots via the MCP roots/list capability and searches those directories for dw.json.

Key behaviors (from the server logic):

• Only runs when no CLI or environment credentials are provided (priority is CLI > ENV > workspace roots).
• Uses roots/list instead of the current working directory.
• Validates file:// URIs only and blocks system directories for safety.
• When a dw.json is found, the server re-registers tools and sends tools/list_changed so your client can see new tools.

If your client does not support roots/list, auto-discovery will be skipped and you must pass --dw-json or environment variables.

Quick start Start in docs mode, then add `dw.json` only when you need logs, job logs, system objects, or code versions.

dw.json builder

dw.json builder

Fill in the fields you need. Empty fields are omitted from the JSON output.

Hostname Username Password Client ID Client Secret Site ID Code Version

{}

Minimal dw.json (logs and job logs)

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password"
}

Full dw.json (Data API and code versions)

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-ocapi-client-id",
  "client-secret": "your-ocapi-client-secret"
}

Supported dw.json fields

Field	Required for	Notes
hostname	All authenticated tools	Sandbox domain (no protocol)
username / password	Logs + job logs	WebDAV credentials
client-id / client-secret	System & custom objects, site prefs, code versions	OCAPI Data API
code-version	Code version operations	Optional default
site-id	Site-specific actions	Optional

Tool availability by mode

Category	Docs only	Authenticated (capability-gated)
Documentation	✔	✔
Agent instructions (AGENTS.md + skills)	✔	✔
SFRA docs	✔	✔
ISML docs	✔	✔
Cartridge generation	✔	✔
Log analysis (runtime)	—	✔ (requires WebDAV creds)
Job logs	—	✔ (requires WebDAV creds)
System & custom objects / site prefs	—	✔ (requires client-id/client-secret)
Code versions	—	✔ (requires client-id/client-secret)

Data API resource mapping

Add these resources in Business Manager: Administration -> Site Development -> Open Commerce API Settings (Data API tab).

{
  "_v": "23.2",
  "clients": [{
    "client_id": "YOUR_CLIENT_ID",
    "resources": [
      { "resource_id": "/system_object_definitions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/system_object_definitions/*", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/system_object_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/system_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/system_object_definitions/*/attribute_group_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/custom_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/site_preferences/preference_groups/*/*/preference_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/code_versions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
      { "resource_id": "/code_versions/*", "methods": ["get", "patch"], "read_attributes": "(**)", "write_attributes": "(**)" }
    ]
  }]
}

Data API setup steps

Step 1: Create API Client (Account Manager)

1. Log in to Account Manager (not Business Manager).
2. Navigate to API Client and add a new client.
3. Generate a client secret and grant SFCC scopes.

Step 2: Business Manager Data API settings

1. Business Manager -> Administration -> Site Development -> Open Commerce API Settings.
2. Add the resource mapping shown above to the Data API tab.
3. Ensure the client ID matches your Account Manager API client.

Step 3: Update dw.json

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-ocapi-client-id",
  "client-secret": "your-ocapi-client-secret"
}

Troubleshooting Data API access

• 403: Missing scope or resource mapping in Business Manager.
• 401: Invalid credentials or expired secret.
• Empty results: Confirm definition_search endpoints are enabled and use match_all_query.

Notes

• Logs and job logs use WebDAV with username and password.
• System objects and site preferences use OCAPI Data API (client-id and client-secret).
• Code version activation requires Data API access plus patch permission.

Debug mode Use `--debug true` temporarily when diagnosing tool behavior.

Tool availability by mode

Category	Docs mode	Full mode
Documentation, SFRA, ISML	Yes	Yes
Cartridge generation	Yes	Yes
Agent instructions	Yes	Yes
Logs and job logs	No	Yes
System objects and site preferences	No	Yes
Code versions	No	Yes
Script debugger	No	Yes

Supported dw.json fields

Field	Required for	Notes
hostname	All authenticated tools	Sandbox hostname
username / password	Logs and job logs	WebDAV access
client-id / client-secret	System objects, site preferences, code versions	OCAPI Data API
code-version	Code version operations	Optional
site-id	Site-specific operations	Optional

Security basics

echo 'dw.json' >> .gitignore
echo '*.dw.json' >> .gitignore
chmod 600 dw.json

Use environment variables for secrets in CI:

export SFCC_CLIENT_SECRET="your-secret"
export SFCC_PASSWORD="your-password"