Crystallize MCP

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 Code (CLI)

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

Use --scope project to write to .mcp.json (shared with your team) or --scope user for personal use across all projects.

Claude Desktop

Add the standard config to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Cursor

Add the standard config to your Cursor MCP settings (~/.cursor/mcp.json or the project-level .cursor/mcp.json).

VS Code / GitHub Copilot

Add the standard config to .vscode/mcp.json in your project root.

{

"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" } } } }

Windsurf

Add the standard config to ~/.codeium/windsurf/mcp_config.json.

Gemini CLI

Add the standard config to ~/.gemini/settings.json.

JetBrains AI Assistant

Add the standard config to .junie/mcp.json in your project root.

Warp

Add the standard config to ~/.warp/mcp.json.

Raycast

Open "Install MCP Server" in Raycast and fill in:

• Command: npx
• Arguments: -y @hayodev/crystallize-mcp@latest
• Environment: add CRYSTALLIZE_TENANT_IDENTIFIER and your token vars

Or copy the standard config JSON above before opening the command — Raycast will auto-fill the form.

From source (maintainers)

The --local flag is for developing crystallize-mcp itself. It writes .mcp.json pointing to the local build output — run this from the repo root only:

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/

Or point your MCP client directly at the built entry point:

{

"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

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:

| none | Contact/PII fields stripped — names, emails, phones, addresses, meta