Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@storefront-mcp validate my cart query, I think I used a numeric cart id"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the CloudCart Storefront GraphQL API — the headless API Nitrogen storefronts, the mobile app and other clients are built on.
It is a developer's assistant, not a shop's. It runs on your machine, reads the schema, and never talks to a store: no access token, no network, nothing that could touch live data.
Its companion is @cloudcart/dev-mcp, which covers the Admin
API. The two APIs differ in more than scope — the Admin API uses plain numeric
ids, the Storefront API uses gid://cloudcart/… — so keep them apart.
Tool | What it is for |
| Call first. The whole API — catalog, collections, search, content, cart, checkout, customers, orders, returns, analytics — and what the schema cannot tell you: how a signed-in buyer is sent (never an |
| Look up a type, query or mutation by name. Flags fields that stay empty unless the merchant runs the app behind them. |
| Check GraphQL before it ships — both against the schema and against the mistakes that validate cleanly and still fail. |
There is deliberately no semantic search. The surface is small enough to look
up by name — data/storefront.json holds every type, query and mutation — and
learn_cloudcart_storefront names the operation for each step; an embedding
index would add size and a cold start to solve a problem this API does not have.
Related MCP server: GraphQL Schema Explorer
Things that pass validation and still go wrong:
a numeric cart id — carts are addressed by their key, and a row number resolves to nothing
reading delivery before there is an address — couriers price against a destination, so the list is empty
reading paymentMethods before delivery is chosen — the courier decides
part of what is allowed
selecting amount without formatted — fine for logic, but a buyer is
shown the amount as the store writes money
a paged product list or search without its facets (filters,
productFilters) or without totalCount — the API already computed them
a metafield asked for without its namespace — the store has no
app-reserved namespace, so a key alone finds nothing
It also answers names borrowed from other storefront APIs — productByHandle,
checkoutCreate, cartDeliveryAddressesAdd, cartGiftCardCodesUpdate,
customerAccessTokenCreate — each coming back with the CloudCart equivalent and
the reason it differs. Most of the
vocabulary is deliberately familiar; these are the places it is not.
npm install
npm run builddata/storefront.json is part of the package: building needs no schema.
generate-schema reads the SDL from the folder in SF_SCHEMA_DIR. Give it the
sf/schema files of the commit production runs, never a working copy: a
developer's queries go to production, and a type that exists only on a branch
would validate here and fail there. Export them from cc-builder:
mkdir -p /tmp/sf-deployed
git -C /path/to/cc-builder archive <deployed commit> sf/schema | tar -x -C /tmp/sf-deployed
SF_SCHEMA_DIR=/tmp/sf-deployed/sf/schema npm run generate-schemaThe schema is assembled from those files rather than fetched from a running store. They are what the server itself builds from — no store, no token, no network.
The CloudCart AI Toolkit plugin registers it. To add it to an MCP host yourself:
{
"mcpServers": {
"cloudcart-storefront-mcp": {
"command": "npx",
"args": ["-y", "@cloudcart/storefront-mcp@latest"]
}
}
}From a local build, the command is node with /absolute/path/to/storefront-mcp/dist/index.js.
Export the deployed commit's sf/schema as above, then:
SF_SCHEMA_DIR=/tmp/sf-deployed/sf/schema npm run generate-schema && npm run buildThe shipped schema comes from that step, so run it after every deploy that
changes sf/schema.
Regenerate the schema from the deployed commit (above), npm run build, and check the three tools.
Bump version in package.json (the server reads it from there), commit, push main; CI builds and checks the tools on Node 20, 22 and 24.
Publish by hand, from a clean clone of that commit: npm ci, npm run build, npm publish --access public with an npm login that may write @cloudcart/storefront-mcp (the account confirms with its security key). Then gh release create vX.Y.Z for the notes; it publishes nothing.
scripts/generate-schema.ts SDL in the repo → data/storefront.json
src/prompts/storefront.ts what an assistant must know before writing anything
src/app-resources.ts which fields depend on a merchant's installed apps
src/tools/ the three tools
src/schema/loader.ts reads and caches the introspection JSON
.github/workflows/ CI on every pushLook up types, queries and mutations in the CloudCart Storefront schema by name.
Use this when you already know what something is called. When you know what you want to do but not what it is called, read learn_cloudcart_storefront's guide first — it names the operation for each step.
It searches the names of types, queries and mutations, not of fields: look up the type that holds a field.
Results flag fields that only answer when the merchant runs the app behind them, which is the usual explanation for an empty list.
| Name | Required | Description | Default |
|---|---|---|---|
| api | No | Which schema to search. | storefront |
| mode | No | `full` expands the best match with all its fields. `compact` returns the summary line only — use it when you already have the signature and just want a sanity check. | full |
| query | Yes | Name or part of a name — 'Cart', 'cartLinesAdd', 'delivery', 'MoneyV2'. | |
| filter | No | Restrict the search to one category. | |
| conversationId | Yes | From learn_cloudcart_storefront. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses that matching is against type/query/mutation names (not fields), and that results flag fields gated behind merchant-run apps, which explains empty lists. It does not discuss auth or result-size limits, but for a read-only schema introspection these are minor omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action in sentence one, followed by usage routing and two caveats. Slightly paragraph-heavy for the amount of information, but each paragraph carries a distinct point and none is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations exist, so the description is the sole source of behavioral context; it covers usage routing and the empty-list explanation. It could say more about what a match looks like in 'full' vs 'compact' mode, but that detail is already in the schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the 'query' parameter matches names of types/queries/mutations and not fields, and that you should look up the containing type instead. The mode/compact and filter semantics are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Look up types, queries and mutations in the CloudCart Storefront schema by name') and immediately scopes it against the sibling learn_cloudcart_storefront. An agent can distinguish it from both siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives the when:'Use this when you already know what something is called,' the when-not:'when you know what you want to do but not what it is called,' and names the alternative tool to use instead. It also warns that only names are searched, not fields, which steers the caller to the right query shape.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this first, before anything else in this server.
It returns a conversationId that every other tool here requires, and — more
usefully — what the CloudCart Storefront API's schema does not show: how a
signed-in buyer is sent (an argument or @inContext(buyer:), never an
Authorization header), that a Nitrogen storefront's checkout is the store's own
(cart.checkoutUrl), that the server owns every price and money is shown as
formatted, and that a cart is addressed by an unguessable key.
Reading it first is the difference between a storefront that works and one that charges the wrong total.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Your model name or id (e.g. 'claude-opus-5'). Used to improve this documentation. | |
| conversationId | No | An existing conversation id. Omit to start a new one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that a signed-in buyer is passed as an argument or @inContext(buyer:), never an Authorization header, that checkout belongs to the store (cart.checkoutUrl), that the server owns prices and money is rendered as `formatted`, and that carts use an unguessable key. It also warns that skipping it produces silently wrong totals. It omits repeat-invocation semantics and the exact shape of the returned guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The imperative call-to-action is front-loaded in the first line, followed by the payoffs in a compact enumerated form. The closing line ('the difference between a storefront that works and one that charges the wrong total') is rhetorical flourish rather than new information, though it does reinforce the stakes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must explain both what comes back and why it matters, and it does: the conversationId plus four concrete API-behavior facts an agent would otherwise get wrong. It stops short of describing the full contents of the returned guidance or flagging whether `model` is expected on first call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are documented in the schema and the baseline is 3. The description reinforces the conversationId's significance (required by every other tool) but never mentions the `model` parameter or how conversationId should be echoed back on later calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the two outputs concretely: a conversationId required by every other tool, plus API knowledge the CloudCart schema omits (buyer auth, checkoutUrl, server-owned pricing, cart key). It never states the purpose in a single crisp sentence (e.g. 'loads the Storefront API usage guide'), and it does not name the sibling tools it precedes, but the effect is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call this first, before anything else in this server' is an explicit ordering rule, and the schema covers the resume case ('Omit to start a new one'). It does not state when the tool can be skipped (already having a valid conversationId for the current session) or whether re-calling is wasteful, so there is no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check GraphQL against the Storefront schema before it reaches a browser.
Always run generated queries and mutations through this. The schema is large and has many close names, and an invented field looks entirely plausible until it fails.
Beyond schema validity it flags mistakes that validate cleanly and still fail at runtime, such as a numeric cart id or reading delivery before the cart has an address, and it answers names borrowed from other storefront APIs with the CloudCart one.
| Name | Required | Description | Default |
|---|---|---|---|
| api | No | Which schema to validate against. | storefront |
| codeblocks | Yes | The code blocks to check. | |
| conversationId | Yes | From learn_cloudcart_storefront. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses that validation goes beyond syntax to semantic runtime errors (numeric cart id, reading delivery before an address exists) and that it maps names borrowed from other storefront APIs to CloudCart equivalents. The main gap is that it never describes the shape or content of the validation response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, front-loaded with the core action, followed by a usage mandate and then the differentiating value. Every sentence is doing work; nothing is redundant with the name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple 3-parameter read-only tool with no output schema, the description covers purpose, timing, and the unexpected extra behaviors well. It is nearly complete, but the absence of any statement about what comes back (error list, corrected code, suggestions) leaves a modest informational gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so api, codeblocks, conversationId, and the nested artifactId/revision fields are already documented. The description adds no parameter-level detail (e.g., what a valid conversationId links to or how multiple blocks are reported), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (validate/check) and resource (GraphQL codeblocks against the Storefront schema), plus the timing rationale ('before it reaches a browser'). It is clearly distinct from its siblings learn_cloudcart_storefront and introspect_graphql_schema, which supply context and schema rather than checking artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit and prescriptive: 'Always run generated queries and mutations through this' tells the agent exactly when to invoke it, and the 'invented field looks plausible' rationale motivates the habit. It doesn't name alternative tools or state when-not-to-use, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0introspect_graphql_schemalearn_cloudcart_storefrontvalidate_graphql_codeblocksScored across 3 tools
Each tool has a clearly distinct role: onboarding/context, schema lookup by name, and validation of generated GraphQL. The descriptions explicitly disambiguate when to use introspection versus the learning guide. An agent should not confuse these purposes.
All tool names are snake_case and follow a verb-first pattern: learn_, introspect_, validate_. The nouns are descriptive and consistently scoped to the CloudCart/GraphQL domain.
Three tools are well-scoped for a schema-assistance server: learn the quirks, look up schema names, and validate code before use. Each tool earns its place without redundancy.
The surface covers onboarding, schema discovery, and validation, which are the core workflows for generating correct Storefront GraphQL. A direct query-execution or field-level search tool is absent, but the described workflow allows agents to work around this via type lookup and validation.
Enable AI assistants to interact seamlessly with Feeef e-commerce stores, products, and orders usi…
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
Check any Shopify store's readiness for ChatGPT & AI shopping agents. Free, no API key, 8 languages.
Serves your design system and coding standards to coding agents, so they stop guessing.
