Skip to content
Crystallize AICrystallize AI

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

Section titled “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

Section titled “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:

    Terminal window
    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

Section titled “Available Tools”

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

ToolDescription
build-mass-operationBuild and validate a Crystallize mass operation file.
fetch-catalog-graphql-schemaFetch the compacted GraphQL schema of the Crystallize Catalogue API for a given tenant.
fetch-content-modelFetch the content model (shapes) from a Crystallize tenant.
fetch-core-graphql-schemaFetch the compacted GraphQL schema of the Crystallize Core API (aka Core Next) for a given tenant.
fetch-discovery-graphql-schemaFetch the compacted GraphQL schema of the Crystallize Discovery API for a given tenant.
fetch-shop-cart-graphql-schemaFetch the compacted GraphQL schema of the Crystallize Shop Cart API for a given tenant.
get-mass-operation-statusRead the status of a Crystallize mass operation bulk task by its taskId.
mutate-coreExecute a GraphQL MUTATION against the Crystallize Core API (aka Core Next).
mutate-shop-cartExecute a GraphQL MUTATION against the Crystallize Shop Cart API.
product-overviewDisplay Crystallize catalogue items (products, documents, folders) as an interactive UI panel of cards.
query-catalogueExecute a GraphQL query against the Crystallize Catalogue API.
query-coreExecute a read-only GraphQL query against the Crystallize Core API (aka Core Next).
query-discoveryExecute a GraphQL query against the Crystallize Discovery API.
query-shop-cartExecute a read-only GraphQL query against the Crystallize Shop Cart API.
run-mass-operationRun a Crystallize mass operation against the tenant.
tenant-overviewDisplay an interactive overview of the Crystallize tenants resolved for this connection.
skillsIMPORTANT: 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.

ParameterTypeRequiredDescription
operationsobjectYesArray of operation objects. Each must have an 'intent' field matching one of the valid intents.
versionstringNoMass 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. Prefer passing `intent`: a one-sentence description of what you want to do (e.g. 'create an order for an existing customer'); the server then returns the schema of every domain that task needs, in one call. Pass `domain` instead when you already know the exact domain. Domains are fine-grained (verbs outside create/update/delete get their own domain). Common ones: order, registerOrder, customer, subscriptionContract, priceList, orderPipeline, orderPipelineStage, flow, webhook, role, userRole, inviteToken, pluginInstallation. Call with neither to get the full list of domains. 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.

ParameterTypeRequiredDescription
domainstringNoThe exact domain to fetch the schema for (e.g. 'order', 'customer', 'subscription'). " + "Takes precedence over `intent`.
intentstringNoWhat you want to do with the Core API, in one sentence " + "(e.g. 'list the orders of a customer and their subscriptions'). " + "The server picks the relevant domains and returns their combined schema.

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.

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

ParameterTypeRequiredDescription
languagestringYesLanguage code used by the Discovery query (e.g. 'en')
hitsarrayYesThe `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.

ParameterTypeRequiredDescription
operationsobjectYesArray of operation objects. Each must have an 'intent' field matching a valid intent.
versionstringNoMass 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.

ParameterTypeRequiredDescription
skillsstring[]YesOne or more skill slugs to retrieve.
referencesstring[]NoOptional: specific reference slugs to include. If omitted, only the main skill document is returned " + "(plus the references `task` needs, when given).
includeAllReferencesbooleanNoIf true, include all references for the requested skills.
taskstringNoWhat you are trying to do, in one sentence (e.g. 'add Klarna to my checkout'). " + "The server picks the references of the requested skills that this task needs. " + "Ignored when `references` or `includeAllReferences` is given.

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:

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

How the Server Picks Context

Section titled “How the Server Picks Context”

The Core API schema and the skill references are too large to send to an agent in full. Two tools can take a one-sentence description of what the agent is trying to do; the server then asks Jev, TypeSafe’s decision model running on Cloudflare Workers AI, what that task needs. The server returns only those parts, in a single call.

How the MCP server picks context with JevThe agent calls a tool with an intent or task. The MCP server gathers the candidates (Core schema domains from the Crystallize API, or skill references), asks Jev one yes/no question per candidate in a single request, keeps those scoring 0.5 or more, and returns one answer. If Jev is slow, down or picks nothing, the server returns what it returned before Jev: the domain index or the reference list.Your agentClaude, Cursor, …Crystallize MCPCloudflare WorkerJevTypeSafe on Workers AICrystallize APIyour tenant1tool call + what it wantsintent / task2schema: introspection84 domains as candidatesskills: candidates are the bundledreferences of the requested skillsone request, one yes/no question per candidate3intent + candidate summaries“is this one needed?” × every candidate4a probability for eachregisterOrder 0.78 · customer 0.54 · …5keep everything ≥ 0.5max 4 domains · max 3 references6one answer, with the picksschema of registerOrder, order,customer · or skill + referencesJev slow (> 8 s), down,or picks nothing →the answer from before Jev:domain index / reference list
The same flow serves fetch-core-graphql-schema (intent) and skills(task). The agent never talks to Jev directly.

Jev does not write text. It answers yes/no questions with a calibrated probability. The server asks one question per candidate (“does this task need it?”), all in a single request, and keeps every candidate scoring 0.5 or more. A task can therefore get one part or several: “list the last 10 orders” gets order, and “find a customer by email and show their subscriptions” gets customer and subscriptionContract.

Tool Input Candidates Jev scores Returned
fetch-core-graphql-schema intent Every Core API domain (84 on a typical tenant), each with its queries and mutations Combined schema of up to 4 domains
skills task The references of the skills the agent requested (title, intro and headings) Main skill document + up to 3 references

Worth knowing:

  • The agent stays in control. An exact domain, explicit references or includeAllReferences skip Jev entirely. Each answer shows what was picked and how confident Jev was, for example registerOrder (78%), order (63%), customer (54%), so the agent can ask for anything missing.
  • Jev never blocks a tool call. If it takes more than 8 seconds, fails, or picks nothing, the tool returns what it returned before Jev: the list of domains, or the skill with its list of references.
  • It is cheap. A schema pick uses about 12.8k input tokens, and a reference pick about 1.7k. Both cost well under a tenth of a cent per call.
  • It is measured. bin/eval-domain-selection.ts and bin/eval-reference-selection.ts in the MCP server package replay real intents and tasks against the live model. Both currently get every needed part in 12 out of 12 cases.

Authentication

Section titled “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.


Crystallize AI