Crystallize MCP

MCP server for Crystallize headless commerce. Gives AI agents read and write access to your catalogue, products, shapes, orders, customers, and tenant config — with deep links back to the Crystallize UI, dry-run safety for mutations, and PII masking for customer data.

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

Getting started

Setup wizard

The interactive wizard handles config, auth tokens, keychain storage, and PII mode in one step:

# Project-level — writes .mcp.json in the current directory (shared with your team)
npx @hayodev/crystallize-mcp --setup

# Global — registers via `claude mcp add` (Claude Code) or writes Claude Desktop config
npx @hayodev/crystallize-mcp --setup --global

Manual config

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

{
  "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 ./build/

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

Tools (16)

Catalogue (4 tools)

Discovery (3 tools)

Shapes & Tenant (3 tools, requires auth)

Orders (2 tools, requires auth)

Customers (2 tools, requires auth)

Content (2 tools, requires auth + write mode)

Write tools

Write tools require CRYSTALLIZE_ACCESS_MODE=write (or admin) and a token with write permissions.

Dry-run mode

Set CRYSTALLIZE_DRY_RUN=true to preview mutations without executing them. The response shows exactly what would change — the mutation payload, before/after values, and a deep link to the item:

"env": {
  "CRYSTALLIZE_ACCESS_MODE": "write",
  "CRYSTALLIZE_DRY_RUN": "true"
}

Example prompts

Create an item:

"Create a new blog post under /blog using the article shape with title 'Getting Started'"

Update a top-level component:

"Find the item at /products/summer-collection and update its description to 'New summer arrivals'"

Update a component inside a content chunk:

"Get the item at /articles/my-post, then update hero.title to 'Updated Headline' and give me the deep link to review the draft"

Update with change summary:

"Get the item at /articles/guides/my-guide, update its title component to 'New Guide Title', give me the deep link, and show a table of which fields in the chunk changed vs remained unchanged with before/after values"

The agent will update the target component in draft only, preserve all sibling components in the chunk, and return a summary like:

No publishing happens — you review the change in the Crystallize UI via the deep link and publish when ready.

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