Shopify Dev MCP

Routes MCP tool calls for Shopify surfaces. Standard lookups, not deep reasoning.

⚠️ Skip if a bundled skill applies

The 7 official Shopify skills ship local validators (scripts/search_docs.mjs, scripts/validate.mjs) that are faster than the MCP and don't require a server round-trip:

Use shopify-dev-mcp ONLY when:

• The surface isn't in the table above (storefront-graphql, customer, partner, payments-apps, functions, hydrogen, liquid, custom-data).
• You're cross-referencing schemas across two surfaces in one conversation.
• The bundled script for an installed skill is unavailable or erroring.

⚠️ NOT for legacy post-purchase

The MCP does NOT index @shopify/post-purchase-ui-extensions-react. validate_component_codeblocks rejects every legacy post-purchase component by design — the validator's polaris-checkout-extensions enum value covers MODERN @shopify/ui-extensions <s-*> web components only.

For the legacy SDK: use the post-purchase-ui-extension skill and validate with tsc --noEmit.

Instructions

1 — Initialize

Call learn_shopify_api with the target api surface. Consult the API Surfaces appendix below to confirm the correct api value. Extract the returned conversationId — pass it to every subsequent call.

2 — Route

Determine which tool answers the question: doc search, schema introspection, extension targets, or full page fetch. Consult the Tools Reference below for parameters and gotchas.

3 — Use

Call the appropriate tool(s). If switching API surfaces mid-conversation, call learn_shopify_api again with the existing conversationId and the new api.

4 — Validate

Before committing any generated code:

• <s-*> component markup → validate_component_codeblocks (mandatory)
• GraphQL queries/mutations → validate_graphql_codeblocks (mandatory)
• Liquid/theme files → validate_theme (mandatory)

5 — Fix and re-validate

If validation fails, fix errors and re-validate. Increment revision on the same artifactId to track iterations. If validation fails twice on the same artifact, stop and surface the error to the user.

API Surfaces

All 15 valid values for the api param on learn_shopify_api:

Note: validate_component_codeblocks accepts one additional value — storefront-web-components — that is NOT valid for learn_shopify_api. See the validator's section below.

Tools Reference

Tool availability varies by MCP server build. Some installations register only a subset (typically: learn_shopify_api, search_docs_chunks, validate_component_codeblocks, validate_graphql_codeblocks, validate_theme). If a tool below is not callable in your environment, fall back to search_docs_chunks.

learn_shopify_api

Purpose: Load API overview and get a conversationId. Must be called before all other tools.

Returns: conversationId (UUID) — required by every subsequent tool call.

Gotchas:

• Call again (with same conversationId) when switching API surfaces. This loads new context without losing conversation state.
• The response includes a component/API index for the surface — use it to guide subsequent search_docs_chunks queries.

search_docs_chunks

Purpose: Semantic search over shopify.dev documentation. Returns relevant doc chunks with URLs.

Gotchas:

• Prefer this over fetch_full_docs for targeted lookups.
• For storefront-graphql, this is the only reliable doc tool — introspect_graphql_schema and fetch_full_docs are restricted.

fetch_full_docs

Purpose: Fetch complete documentation pages by path. Use when you need full property/slot/event details from a page found via search_docs_chunks.

Gotchas:

• The learn_shopify_api response labels fetch_full_docs as DEPRECATED for some surfaces, but where present the tool still works. Prefer search_docs_chunks; fall back to fetch_full_docs for complete property/slot/event docs.
• For storefront-graphql, this tool is restricted — use search_docs_chunks instead.
• May not be registered in all MCP server builds.

validate_component_codeblocks

Purpose: Validate <s-*> web component markup against Shopify's schema. Catches hallucinated components, props, and prop values.

Input format: Wrap code in a function — JS logic outside return, components inside return:

const Example = () => {
  const [value, setValue] = useState('');

  return (
    <s-page heading="Example">
      <s-section>
        <s-text-field label="Name" value={value} />
      </s-section>
    </s-page>
  );
};

Raw HTML also works, but the function wrapper is recommended.

Gotchas:

• The param is code (array), not codeblocks — opposite naming from validate_graphql_codeblocks.
• Mandatory after generating ANY <s-*> markup — never skip, even for small snippets.
• For polaris-checkout-extensions, pass the specific extensionTarget (e.g. purchase.checkout.block.render) to get accurate validation.
• The validator does not type App Bridge web components (<s-app-window>, <s-app-nav>) as JSX intrinsic elements — they will fail validation in TSX even though they're real components. Use raw HTML, the App Bridge React wrappers (<TitleBar>, <NavMenu>), or a JSX type augmentation.

GraphQL API enum

IMPORTANT — this enum differs from learn_shopify_api.

validate_graphql_codeblocks and introspect_graphql_schema share an expanded 18-value enum where functions splits into 13 specific subtypes. admin-execution is NOT in this enum — even though it's valid for learn_shopify_api.

validate_graphql_codeblocks

Purpose: Validate GraphQL queries/mutations against the Shopify schema. Catches hallucinated fields and operations.

Gotchas:

• The param is codeblocks (array), not code — opposite naming from validate_component_codeblocks.
• Content must be raw GraphQL, not wrapped in markdown code fences.
• For Functions, use the specific functions_* subtype from the GraphQL API enum, not functions.

introspect_graphql_schema

Purpose: Explore GraphQL schema — find fields, types, queries, mutations, and required scopes.

Fallback strategy (confirmed accurate):

1. Start with the most specific term from the request.
2. If no results, try broader terms or individual words (e.g. captureSession → try capture).
3. For list operations, try all, list, or the plural object name.
4. For mutations, try the action verb: create, update, delete.

Gotchas:

• Uses the same expanded api enum as validate_graphql_codeblocks — functions splits into 13 subtypes.
• For storefront-graphql, this tool is restricted — use search_docs_chunks instead.
• May not be registered in all MCP server builds.

learn_extension_target_types

Purpose: Get type declarations for components and APIs available within a specific extension target.

Supported surfaces:

• polaris-admin-extensions
• polaris-checkout-extensions
• polaris-customer-account-extensions
• pos-ui

Not supported:

• polaris-app-home — not an extension surface.

May not be registered in all MCP server builds. When unavailable, look up valid extension targets via search_docs_chunks instead.

validate_theme

Purpose: Validate Liquid and theme files (JSON locales, config, templates, JS, CSS, SVG).

Validation Reference

Required params per surface for validate_component_codeblocks

Artifact tracking

Both validate_component_codeblocks and validate_graphql_codeblocks support iterative tracking:

• artifactId — Stable ID for the code artifact. Omit on first validation (the tool generates one). Reuse the returned ID on subsequent validations of the same artifact.
• revision — Starts at 1. Increment on each re-validation of the same artifactId. Tracks validation retries vs. new validations.