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

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.

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.