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, manage orders, handle checkout flows, and modify your content structure.

Coming Soon

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.
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.
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.

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.

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.

If you already have skills installed locally (e.g., via the Claude Plugin), you can disable them on the MCP Server by appending ?exposeSkills=false to the URL.

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.