Crystallize MCP Server

The Crystallize MCP Server lets AI agents interact with your Crystallize tenant through the Model Context Protocol. It runs on Cloudflare Workers and provides authenticated access to query and mutate your Crystallize data.

What You Can Do

Query Data

Read catalogue items, products, orders, customers, and more from your tenant using Core, Discovery, Catalogue, and Shop APIs.

Fetch Content Model

Retrieve and inspect your tenant’s shapes, components, and content structure to understand your schema.

Introspect GraphQL Schemas

Fetch compacted GraphQL schemas for the Catalogue and Discovery APIs to understand available queries, types, and fields before writing queries.

Mutate Data

Create and update items, components, and folders, modify cart state, and run bulk mass operations through the Core and Shop APIs. Write tools are off by default — opt in with ?exposeWrite=true.

Opt-in

Access Skills

Get on-demand documentation about Crystallize concepts like content modeling, pricing, and information architecture.

Setup

1. Generate Access Tokens

   In the Crystallize Admin, create a new User with a Read-Only Role and generate Access Tokens for that user.

   We recommend starting with read-only access. You can create a separate user with write permissions if you need mutation capabilities.

2. Install the MCP Server

   Use add-mcp to register the server with your AI client:

   npx add-mcp https://mcp.crystallize.com/mcp \
       --header "X-Crystallize-Access-Token-Id: ACCESS_TOKEN_ID" \
       --header "X-Crystallize-Access-Token-Secret: ACCESS_TOKEN_SECRET"

   This works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.).

3. Verify the connection

   Ask your AI agent to list the available tools — you should see the Crystallize tools ready to use.

Available Tools

The following tools are auto-generated from the MCP Server source code.

Tool	Description
build-mass-operation	Build and validate a Crystallize mass operation file.
fetch-catalog-graphql-schema	Fetch the compacted GraphQL schema of the Crystallize Catalogue API for a given tenant.
fetch-content-model	Fetch the content model (shapes) from a Crystallize tenant.
fetch-core-graphql-schema	Fetch the compacted GraphQL schema of the Crystallize Core API (aka Core Next) for a given tenant.
fetch-discovery-graphql-schema	Fetch the compacted GraphQL schema of the Crystallize Discovery API for a given tenant.
fetch-shop-cart-graphql-schema	Fetch the compacted GraphQL schema of the Crystallize Shop Cart API for a given tenant.
get-mass-operation-status	Read the status of a Crystallize mass operation bulk task by its taskId.
mutate-core	Execute a GraphQL MUTATION against the Crystallize Core API (aka Core Next).
mutate-shop-cart	Execute a GraphQL MUTATION against the Crystallize Shop Cart API.
product-overview	Display Crystallize catalogue items (products, documents, folders) as an interactive UI panel of cards.
query-catalogue	Execute a GraphQL query against the Crystallize Catalogue API.
query-core	Execute a read-only GraphQL query against the Crystallize Core API (aka Core Next).
query-discovery	Execute a GraphQL query against the Crystallize Discovery API.
query-shop-cart	Execute a read-only GraphQL query against the Crystallize Shop Cart API.
run-mass-operation	Run a Crystallize mass operation against the tenant.
tenant-overview	Display an interactive overview of the Crystallize tenants resolved for this connection.
skills	IMPORTANT: Call this tool FIRST before using any other Crystallize tool.

build-mass-operation

Build and validate a Crystallize mass operation file. Validates operations against the official schema and returns either a valid JSON file or detailed error feedback.

Parameter	Type	Required	Description
operations	object	Yes	Array of operation objects. Each must have an 'intent' field matching one of the valid intents.
version	string	No	Mass operation file version. Defaults to '1.0.0'.

fetch-catalog-graphql-schema

Fetch the compacted GraphQL schema of the Crystallize Catalogue API for a given tenant. BEFORE calling this tool, call the `skills` tool first to get documentation and query examples — skills often provide enough context to build queries without needing the full schema. Use this as a second step when you need to understand specific types or fields not covered by the skills. The Catalogue API is a storefront API for fetching items, products, and content to build frontends — it provides path-based reads with strong consistency and union types for components.

fetch-content-model

Fetch the content model (shapes) from a Crystallize tenant. If you haven't already, call the `skills` tool first — it explains how content models work and what to expect from the shape data. Returns all shapes with their name, identifier, type, and resolved configuration. Use this to understand the structure and schema of a tenant's content.

fetch-core-graphql-schema

Fetch the compacted GraphQL schema of the Crystallize Core API (aka Core Next) for a given tenant. BEFORE calling this tool, call the `skills` tool first to get documentation and query examples — skills often provide enough context to build queries without needing the full schema. The Core API schema is large, so it is split into domains. You MUST provide a `domain` parameter. Common domains: order, customer, subscription, subscriptionPlan, pricelist, pipeline, flow, app, user, webhook, stockLocation, invite. If the domain you need is not listed, call without `domain` to get the full list. The Core API is the admin API — use it for orders, customers, price lists, users, subscriptions, subscription plans, pipelines, flows, apps, and other back-office/admin resources. Do NOT use this for fetching items or products for storefronts — use Catalogue or Discovery APIs instead.

Parameter	Type	Required	Description
domain	string	No	The domain to fetch the schema for (e.g. 'order', 'customer', 'subscription'). " + "Omit to get the full list of available domains.

fetch-discovery-graphql-schema

Fetch the compacted GraphQL schema of the Crystallize Discovery API for a given tenant. BEFORE calling this tool, call the `skills` tool first to get documentation and query examples — skills often provide enough context to build queries without needing the full schema. Use this as a second step when you need to understand specific types or fields not covered by the skills. The Discovery API is a storefront API for searching, browsing, filtering, and faceting items and products to build frontends — it uses a shape-typed schema where each shape in the tenant becomes a GraphQL type.

fetch-shop-cart-graphql-schema

Fetch the compacted GraphQL schema of the Crystallize Shop Cart API for a given tenant. BEFORE calling this tool, call the `skills` tool first to get documentation and query examples — skills often provide enough context to build queries without needing the full schema. Use this as a second step when you need to understand specific types or fields not covered by the skills. The Shop Cart API handles cart operations — creating carts, adding/removing items, applying discounts, and reading cart state. Do NOT use this for orders or subscription contracts — those are separate Shop API endpoints.

get-mass-operation-status

Read the status of a Crystallize mass operation bulk task by its taskId. Use this to poll a task started with `run-mass-operation`. Read-only.

Parameter	Type	Required	Description
taskId	string	Yes	The bulk task id returned by run-mass-operation.

mutate-core

Execute a GraphQL MUTATION against the Crystallize Core API (aka Core Next). This WRITES to the tenant — create/update/publish items, components, folders, and other PIM resources. If you haven't already, call the `skills` tool first — it provides mutation examples and best practices. Only mutations are allowed here — for reads use the `query-core` tool instead. The mutation is executed exactly once; it is never auto-corrected or retried, so verify your query first. For large batches of changes, prefer `run-mass-operation`.

mutate-shop-cart

Execute a GraphQL MUTATION against the Crystallize Shop Cart API. This WRITES cart state — create carts, add/remove items, apply discounts. If you haven't already, call the `skills` tool first — it provides mutation examples and best practices. Only mutations are allowed here — for reads use the `query-shop-cart` tool instead. The mutation is executed exactly once; it is never auto-corrected or retried. Do NOT use this for orders or subscription contracts — those are separate Shop API endpoints.

product-overview

Display Crystallize catalogue items (products, documents, folders) as an interactive UI panel of cards. Use this AFTER calling `query-discovery` when the user wants to *see* items rather than inspect raw data — for example when the user asks 'show me red shoes' or 'find products under $50'. Pass the `hits` array (and optional `summary`) returned by the Discovery query along with the `tenant` and `language`. Tip: project at least `name`, `path`, `type`, and `defaultVariant { firstImage { url }, defaultPrice, sku, priceVariants { currency, identifier, price } }` for the best card rendering. Include `variants { sku, name, isDefault, defaultPrice, firstImage { url } }` if you want a variant switcher in the detail view. Components and other rich content fields are not rendered.

Parameter	Type	Required	Description
language	string	Yes	Language code used by the Discovery query (e.g. 'en')
hits	array	Yes	The `hits` array returned by a Discovery `search` or `browse` query

query-catalogue

Execute a GraphQL query against the Crystallize Catalogue API. If you haven't already, call the `skills` tool first — it provides query examples and best practices that will help you write correct queries. The Catalogue API is a storefront API for fetching items, products, and content to build frontends. Use this for reading specific items by path or ID, traversing the catalogue tree, and accessing detailed component data with full type support.

query-core

Execute a read-only GraphQL query against the Crystallize Core API (aka Core Next). If you haven't already, call the `skills` tool first — it provides query examples and best practices that will help you write correct queries. The Core API is the admin API — use it for orders, customers, price lists, users, subscriptions, subscription plans, pipelines, flows, apps, and other back-office/admin resources. Only queries are allowed — mutations are blocked. Do NOT use this for fetching items or products for storefronts — use Catalogue or Discovery APIs instead.

query-discovery

Execute a GraphQL query against the Crystallize Discovery API. If you haven't already, call the `skills` tool first — it provides query examples and best practices that will help you write correct queries. The Discovery API is a storefront API for searching, browsing, filtering, and faceting items and products to build frontends. It uses a shape-typed schema where each shape in the tenant becomes a GraphQL type. Use this for searching, filtering, listing items, and aggregating data for storefront use cases.

query-shop-cart

Execute a read-only GraphQL query against the Crystallize Shop Cart API. If you haven't already, call the `skills` tool first — it provides query examples and best practices that will help you write correct queries. The Shop Cart API handles cart operations — creating carts, adding/removing items, applying discounts, and reading cart state. Only queries are allowed — mutations are blocked. Do NOT use this for orders or subscription contracts — those are separate Shop API endpoints.

run-mass-operation

Run a Crystallize mass operation against the tenant. This WRITES — it validates the operations, uploads them, creates a bulk task, and starts it in one shot. Use `build-mass-operation` first to validate your operations, and `fetch-content-model` to understand the tenant's shapes. The task runs asynchronously: this returns a taskId and initial status — poll `get-mass-operation-status` to follow its progress.

Parameter	Type	Required	Description
operations	object	Yes	Array of operation objects. Each must have an 'intent' field matching a valid intent.
version	string	No	Mass operation file version. Defaults to '1.0.0'.

tenant-overview

Display an interactive overview of the Crystallize tenants resolved for this connection. Shows tenant name, identifier, ID, and auth type as a UI panel rendered in the host. Use this when the user wants to inspect or confirm which tenants are connected.

skills

IMPORTANT: Call this tool FIRST before using any other Crystallize tool.

Parameter	Type	Required	Description
skills	string[]	Yes	One or more skill slugs to retrieve.
references	string[]	No	Optional: specific reference slugs to include. If omitted, only the main skill document is returned.
includeAllReferences	boolean	No	If true, include all references for the requested skills.

The server is read-only by default. The following query parameters can be appended to the server URL to change which tools are exposed:

Query parameter	Default	Effect
exposeWrite=true	off	Exposes the write tools (mutations and mass operations). Off by default for safety.
exposeSkills=false	on	Hides the skills tool — useful if you already have Skills installed (e.g. via the Claude Plugin).
exposeUi=false	on	Hides UI-panel tools (tenant-overview, product-overview).

For example, to enable writes:

npx add-mcp "https://mcp.crystallize.com/mcp?exposeWrite=true" \
    --header "X-Crystallize-Access-Token-Id: ACCESS_TOKEN_ID" \
    --header "X-Crystallize-Access-Token-Secret: ACCESS_TOKEN_SECRET"

Enabling exposeWrite only makes the tools available — the access token’s user must also have the required write permissions in Crystallize for mutations to succeed.

Authentication

The MCP Server requires two headers on every request:

Header	Description
X-Crystallize-Access-Token-Id	Your Crystallize access token ID
X-Crystallize-Access-Token-Secret	Your Crystallize access token secret

These credentials are passed through to Crystallize APIs, so the agent operates with the same permissions as the token’s associated user.