Shopify Dev MCP: What It Is and How to Use It (2026 Guide)

Why Your AI Assistant Keeps Inventing Shopify GraphQL Fields

Ask an AI assistant to write a Shopify Admin API mutation without any guardrails, and there's a decent chance it will hand you code that references a field that doesn't exist. The query looks plausible. It compiles in your head. Then you run it and the API returns Field 'productUpdateMedia' doesn't exist on type 'Mutation'.

This is the exact problem the Shopify Dev MCP server solves. Instead of letting your AI assistant guess at Shopify's APIs from stale training data, Shopify Dev MCP gives it live access to current documentation, real GraphQL schemas, and a validation layer that catches hallucinated code before it ever reaches your terminal. If you're building apps, themes, or custom storefronts with AI assistance, it's the single highest-leverage tool you can add to your setup — and this guide covers everything from how the protocol works to working configs for Claude Code, Cursor, and VS Code, with links to deeper tutorials across our Shopify development resources.

Training data has an expiration date

Every large language model is frozen at its training cutoff. Shopify, meanwhile, ships API changes on a quarterly release cadence — new API versions arrive every three months, and each version is only supported for a year.

That mismatch means an AI model's "knowledge" of the Admin API is often two to four versions behind. Fields get renamed, mutations get deprecated, and entire resources move. The model doesn't know any of this happened.

The REST-to-GraphQL migration made it worse

Shopify declared the REST Admin API legacy and pushed all new development toward GraphQL. Models trained on a decade of REST-heavy tutorials still reach for REST patterns by default.

The result is a worst-case combination: AI assistants confidently producing code in a deprecated paradigm, sprinkled with GraphQL fields that were never real. Without a source of truth, you become the validation layer.

What a hallucinated mutation costs you

A fabricated field isn't just an error message. It costs you:

• Debugging time — you assume your logic is wrong before suspecting the field name
• Trust erosion — after a few bad suggestions, you stop delegating API work to the assistant at all
• Review overhead — every AI-generated query needs a manual schema check
• Broken automations — a mutation that fails silently in a background job can corrupt store data workflows

Schema-validated generation eliminates that entire category of failure. That's the core promise of Shopify Dev MCP.

What the Model Context Protocol Actually Is

Before the Shopify-specific part makes sense, you need the protocol underneath it. The Model Context Protocol (MCP) is an open standard — originally introduced by Anthropic in late 2024 and now supported across the major AI tooling ecosystem — for connecting AI applications to external systems.

The canonical analogy: MCP is a USB-C port for AI. Just as USB-C standardized how devices connect to accessories, MCP standardizes how AI assistants connect to data sources and tools. Build a server once, and any MCP-compatible client — Claude Code, Cursor, VS Code, Codex, Gemini CLI — can use it.

Servers, clients, and tools in plain English

MCP has three moving parts worth understanding:

1. MCP client — the AI application you're typing into (Claude Code, Cursor, etc.)
2. MCP server — a small program that exposes capabilities, like "search Shopify docs"
3. Tools — the individual functions a server offers, which the AI calls when it decides it needs them

When you ask your assistant a Shopify question, the model recognizes it needs real data, calls the relevant tool on the server, gets structured results back, and folds them into its answer. You see none of the plumbing — just a dramatically more accurate response.

Why an open standard beats one-off integrations

Before MCP, every AI tool needed a bespoke integration with every data source — an N-times-M explosion of connectors. With MCP, Shopify maintains one server and every compatible editor benefits.

For you as a developer, this means your configuration is portable. The same @shopify/dev-mcp server works identically whether you switch from Cursor to Claude Code or run both side by side.

What the Shopify Dev MCP Server Gives Your AI Assistant

The Shopify Dev MCP server is Shopify's official MCP server for development work. It runs locally on your machine, requires no authentication and no API keys, and connects your assistant to three things it otherwise can't reach.

Documentation search that's always current

The server queries shopify.dev's documentation directly. When your assistant needs to know how app subscriptions billing works or what scopes a webhook topic requires, it searches the live docs instead of reconstructing an answer from training data.

This matters most for anything that changed recently — checkout extensibility, Shopify Functions, customer account extensions — where training data is most likely to be wrong or missing entirely.

GraphQL schema introspection on demand

This is the headline feature. The server can introspect the actual GraphQL schemas for Shopify's APIs — Admin, Storefront, Partner, Customer Account, Payments Apps, and Functions — and return exactly the portion of the schema relevant to your prompt.

Ask for "the fields available on a product variant" and your assistant gets the real, current type definition with every field, argument, and deprecation notice. No guessing. No outdated field names.

Validated code generation before you ever run it

Introspection prevents most hallucinations; validation catches the rest. The Shopify Dev MCP server includes tools that check generated code blocks against the real schema before they're presented as final output.

If the model drafts a mutation with a fabricated field, validation fails, the model sees the error, and it corrects itself — all inside one response. You receive code that has already survived a schema check. That loop — generate, validate, fix, validate again — is why schema validation beats raw generation every time.

The Tools Inside @shopify/dev-mcp

The server ships as an npm package, @shopify/dev-mcp, and exposes a small, focused set of tools. Knowing what they do helps you understand what your assistant is actually doing when you watch tool calls scroll by.

learn_shopify_api comes first

The learn_shopify_api tool is the entry point. It teaches the model which Shopify APIs the server supports and how to use the other tools correctly, and it establishes a conversation ID that threads the subsequent calls together.

If your assistant skips this step, the other tools will nudge it to call this one first. It's effectively the orientation briefing for the rest of the session.

search_docs_chunks and fetch_full_docs

These two handle documentation:

• `search_docs_chunks` — keyword search across shopify.dev, returning the most relevant fragments for fast lookups
• `fetch_full_docs` — retrieves a complete documentation page when the assistant needs full context rather than snippets

In practice, the assistant searches first, then fetches the full page only when a fragment isn't enough — the same workflow you'd use yourself, just automated.

The introspection and validation tools

The remaining tools do the schema work:

• `introspect_graphql_schema` — pulls the relevant slice of any supported Shopify GraphQL schema, including queries, mutations, types, and required access scopes
• `validate_graphql_codeblocks` — checks generated GraphQL against the real schema and rejects hallucinated fields or operations
• `validate_component_codeblocks` and `validate_theme_codeblocks` — extend the same validation idea to Polaris components and theme/Liquid code

The npm package README also documents opt-in environment flags for enabling additional surfaces (such as Polaris support), so check it for the current list when you configure the server.

Shopify Dev MCP vs the Other Shopify MCP Servers

"Shopify MCP" is an overloaded term in 2026 — Shopify maintains several servers with very different jobs, and mixing them up is the most common point of confusion. Here's the map:

Storefront MCP: agentic shopping, not coding

The Storefront MCP server lets AI agents like ChatGPT or Perplexity search a store's products, build carts, and answer policy questions on behalf of shoppers. It's commerce infrastructure, not a development tool.

If you're building headless experiences that consume it, our deep-dive on using the Storefront API MCP for headless development covers that side in detail.

Customer Account MCP: post-purchase self-service

The Customer Account MCP server gives authenticated AI experiences access to a customer's own orders and account data — think "where's my order?" handled by an agent instead of a support ticket. It requires customer authentication, unlike the Dev MCP server.

Community-built servers fill the store-data gap

The official Dev MCP server deliberately never touches your store. Community projects like GeLi2001's shopify-mcp connect AI assistants to live store data through the Admin API with an access token — useful for "show me yesterday's orders" workflows, but you're trusting third-party code with store credentials. Vet anything you install, scope tokens minimally, and prefer read-only scopes where possible.

How the Shopify AI Toolkit Changes the Picture

In April 2026, Shopify bundled its AI developer tooling into the Shopify AI Toolkit — an open-source, MIT-licensed package that wraps the Dev MCP server into auto-updating plugins for supported editors, published on GitHub at Shopify/shopify-ai-toolkit.

Plugin, skills, or raw MCP server — pick one

The toolkit gives you three installation paths:

1. Plugin (recommended by Shopify) — auto-updates, bundles the MCP server plus agent skills
2. Agent skills — markdown skill files you cherry-pick from the GitHub repo for specific tasks
3. Dev MCP server only — the classic npx @shopify/dev-mcp setup, which is still the most portable option

If you just want accurate docs and validated GraphQL, the MCP server alone is enough. The plugin adds task-specific skills on top.

What the skills actually cover

The toolkit ships with skill files covering core platform areas — products, inventory, orders, themes, metafields, and more. Combined with Shopify CLI access, this is what lets agents go beyond answering questions into executing work: scaffolding apps, running bulk product updates, and editing metafields at scale.

A caution about mutation access

Once an agent can execute Admin API mutations through your CLI session, its changes hit your live store immediately — there's no draft mode and no undo, a caveat that third-party reviews like Ask Phill's AI Toolkit breakdown rightly emphasize. Run destructive workflows against a development store first, always.

Setting Up Shopify Dev MCP in Claude Code

Claude Code is the assistant we see most often in the Talk Shop community, and setup takes under a minute.

The one-command install

From any terminal, run:

claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

Restart Claude Code, and the server is live. The npx -y invocation means there's nothing to install globally — the latest version is fetched on launch.

The plugin route

If you want the full AI Toolkit (MCP server plus skills), install the plugin instead from within Claude Code:

/plugin marketplace add Shopify/shopify-ai-toolkit
/plugin install shopify-plugin@shopify-plugin

The plugin auto-updates, which matters on a platform that revs its APIs quarterly.

Verify it's actually working

Ask something only the live schema can answer — "introspect the productSet mutation and list its input fields." If you see tool calls to learn_shopify_api and introspect_graphql_schema in the output, you're connected. For a deeper walkthrough of this exact setup, including troubleshooting, see our dedicated guide to Shopify Dev MCP for Claude Code, and for the broader workflow context, our overview of Claude Code for Shopify development.

Setting Up Shopify Dev MCP in Cursor and VS Code

The same server works in every major MCP-compatible editor — only the config location changes.

Cursor

Open Settings → Tools and MCP → New MCP server and add:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

On Windows, if npx fails to spawn, wrap it: "command": "cmd" with "args": ["/k", "npx", "-y", "@shopify/dev-mcp@latest"].

VS Code

Open the Command Palette, run "MCP: Open User Configuration", and add the server to mcp.json (note the key is servers, not mcpServers):

{
  "servers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

Codex and Gemini CLI

Codex CLI takes a TOML block in ~/.codex/config.toml:

[mcp_servers.shopify-dev-mcp]
command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]

Gemini CLI uses the same mcpServers JSON shape as Cursor inside its settings.json. One server definition, five editors — that's the MCP portability payoff.

A Real Workflow: From Prompt to Validated Mutation

Here's what working with the server looks like on an actual task — say, writing a mutation that updates metafields on a batch of products.

Step 1: Ground the assistant

Prompt: "Using the Shopify Dev MCP, find the current recommended mutation for setting product metafields in bulk." The assistant calls learn_shopify_api, then search_docs_chunks, and comes back citing metafieldsSet with the current API version's constraints — not whatever pattern was popular in its training data.

Step 2: Introspect before writing

Next, the assistant calls introspect_graphql_schema for the mutation's input types. It now knows the exact shape of MetafieldsSetInput, which fields are required, and what the 25-metafield-per-call limit means for your batching logic.

Step 3: Generate, validate, repeat

The assistant drafts the mutation and runs validate_graphql_codeblocks on its own output. If validation flags a bad field, it fixes the code and validates again before showing you anything. From there you can wire the mutation into an app or script — and if you're going further down that road, our guides on whether Claude Code can build full Shopify apps and integrating Claude Code with the Shopify CLI pick up exactly where this workflow ends.

What Shopify Dev MCP Can't Do

Honest expectations prevent disappointed Discord posts. The Dev MCP server has deliberate boundaries.

It never touches your store

The Dev MCP server is read-only against documentation and schemas. It cannot read your products, modify your theme, or run mutations against your Admin API. That's by design — it's why no authentication is needed and why it's safe to install without thinking hard about credentials.

Store operations require either the AI Toolkit's CLI-backed skills or a community MCP server with an access token — both of which deserve the caution covered earlier.

It won't replace judgment

Validation guarantees your GraphQL is schema-correct, not business-correct. A perfectly valid mutation can still set the wrong metafield namespace, target the wrong products, or ignore your app's rate-limit budget. Architecture decisions, API version migration timing, and data-model design still belong to you.

Common Mistakes to Avoid with Shopify Dev MCP

After watching dozens of setups in our community, the same handful of mistakes keep appearing.

Setup mistakes

Workflow mistakes

• Not prompting for validation — most assistants validate automatically, but on long sessions it's worth explicitly asking "validate that against the schema" for anything destined for production
• Letting the assistant skip introspection on "easy" queries — simple-looking fields are exactly where deprecations hide
• Testing mutation workflows on a live store — use a development store until the workflow is proven
• Treating docs-search answers as a substitute for reading the page — for anything billing- or compliance-related, have the assistant fetch the full doc and read it yourself

Keep Building: Shopify Dev MCP Is the New Baseline

A year ago, AI-assisted Shopify development meant constant schema-checking and a healthy distrust of every generated query. Shopify Dev MCP flips that: live docs search, real schema introspection, and validated codegen turn your AI assistant from a confident guesser into a grounded pair programmer. Setup is one command in Claude Code and one JSON block in Cursor or VS Code, the server runs locally with zero credentials, and the April 2026 AI Toolkit wraps it all in an auto-updating plugin.

The configs in this guide will get you running, but the interesting part is what happens next — the prompting patterns, skill combinations, and agent workflows people are discovering weekly. That conversation is happening live in the Talk Shop Discord's dev community, where Shopify developers swap MCP configs, compare AI workflows, and debug each other's setups in real time. Join us and bring your weirdest validation error — what's the first workflow you'd hand off to a schema-grounded assistant?

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.