Crystallize MCP

MCP server for Crystallize headless commerce. Gives AI agents read access to your catalogue, products, shapes, orders, customers, and tenant config — with deep links back to the Crystallize UI.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, Copilot, and any MCP-compatible client.

Getting started

Standard MCP config (works in any client):

{
  "mcpServers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
      }
    }
  }
}

Add CRYSTALLIZE_ACCESS_TOKEN_ID and CRYSTALLIZE_ACCESS_TOKEN_SECRET to the env block for PIM tools (shapes, orders, customers). See Authentication.

claude mcp add crystallize \
  -e CRYSTALLIZE_TENANT_IDENTIFIER=your-tenant \
  -e CRYSTALLIZE_ACCESS_TOKEN_ID=your-token-id \
  -e CRYSTALLIZE_ACCESS_TOKEN_SECRET=your-token-secret \
  -- npx -y @hayodev/crystallize-mcp@latest

npx @hayodev/crystallize-mcp --setup

npx @hayodev/crystallize-mcp --setup --global

{
  "servers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant",
        "CRYSTALLIZE_ACCESS_TOKEN_ID": "your-token-id",
        "CRYSTALLIZE_ACCESS_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

git clone https://github.com/HayoDev/crystallize-mcp.git
cd crystallize-mcp
npm install && npm run build
npx . --setup --local   # writes .mcp.json pointing to local build

{
  "mcpServers": {
    "crystallize": {
      "command": "node",
      "args": ["/path/to/crystallize-mcp/build/src/bin/crystallize-mcp.js"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
      }
    }
  }
}

Tools (12)

Catalogue (4 tools)

Discovery (3 tools)

Shapes & Tenant (3 tools, requires auth)

Orders (2 tools, requires auth)

Customers (2 tools, requires auth)

Authentication

Catalogue and Discovery tools work without auth — just set CRYSTALLIZE_TENANT_IDENTIFIER.

For PIM tools (shapes, tenant info, orders, customers), create an access token at: https://app.crystallize.com/{tenant}/en/settings/access-tokens

Note: Crystallize tokens inherit permissions from the user who created them. To restrict an agent to read-only access, generate the token under a user with a read-only role. See Crystallize Roles.

Environment variables

PII mode (opt-in)

By default all customer and order data is returned as-is (full). Set CRYSTALLIZE_PII_MODE to opt in to data minimisation:

Applies to list_customers, get_customer, list_orders, and get_order. No effect on catalogue or shape tools.

Relevant for teams handling real customer data, GDPR Article 25 compliance (data minimisation by design), or environments where the AI doesn't need raw contact details to do its job. A common pattern is masked on production and full on dev.

Audit log (opt-in)

Set CRYSTALLIZE_AUDIT_LOG to an absolute file path to enable structured logging of every tool call:

{
  "ts": "2026-04-03T14:38:41Z",
  "tool": "list_customers",
  "params": { "first": 10 },
  "result": "ok",
  "tenant": "hageland-prod"
}

One JSON line per call — timestamp, tool name, params, result (ok/error), and tenant. Response content is never logged.

Note: Params are logged as-is and may contain PII — for example, a searchTerm of hani@example.com or a customerIdentifier. Treat the audit log file as sensitive data and restrict access accordingly. Param scrubbing is on the roadmap but not yet implemented.

Easy to pipe into log aggregators (Datadog, CloudWatch, Splunk) — but ensure your pipeline handles the file with appropriate access controls.

Keychain storage (optional)

The setup wizard (npx @hayodev/crystallize-mcp --setup) can store tokens in the OS keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux) so they never appear as plain text in config files. This is particularly useful for:

• Claude Desktop users — config is written to a JSON file with no CLI equivalent for secret management
• Shared .mcp.json — when your project config is committed to git, keychain storage keeps tokens out of the repository

When tokens are in the keychain, the config only needs CRYSTALLIZE_TENANT_IDENTIFIER — credentials are resolved automatically at startup.

Note: CLI-based MCP clients (claude mcp add, Cursor, Copilot, etc.) store env vars as plain text in their config files and do not integrate with the OS keychain directly. If plain text env vars in a local config file are acceptable for your setup, the wizard's keychain option is not needed.

Access mode

CRYSTALLIZE_ACCESS_MODE controls which tools the MCP server registers at startup:

• read (default) — read-only tools only
• write — includes tools that can create/update content (Phase 3)
• admin — full access including webhooks and tenant config (Phase 3)

Deep links

Every response includes clickable links to the Crystallize UI:

• Items → app.crystallize.com/@{tenant}/{language}/catalogue/{type}/{itemId}
• Shapes → app.crystallize.com/@{tenant}/{language}/settings/shapes/{identifier}
• Orders → app.crystallize.com/@{tenant}/{language}/orders/{orderId}

The language segment is automatically set from the tenant's default language, bootstrapped at server startup — no configuration needed. Tools that accept a language parameter (catalogue, search) use the requested language in both the API call and the generated link.

Development

npm install
npm run build
npm run dev          # build + start
npm run lint         # oxlint
npm run format       # oxlint --fix + oxfmt
npm run typecheck    # tsc --noEmit
npm run test         # build + node --test

License

MIT