How to Set Up the Shopify AI Toolkit with OpenAI Codex

Key takeaways

• Codex supports the plugin method (codex plugin add shopify@openai-curated), manual skills and MCP.
• Manual skills installation works but schemas drift from the live platform without manual updates.
• MCP configuration for Codex uses TOML format, unlike JSON for Cursor and Gemini CLI.
• Set OPT_OUT_INSTRUMENTATION=true before your first validation if you’re working with proprietary code.
• Store operations execute immediately on your live store. There is no draft step and no undo.

To set up the Shopify AI Toolkit in OpenAI Codex, run codex plugin add shopify@openai-curated in your terminal, or run /plugins in the Codex CLI, search for Shopify and select Add to Codex. Then ask a Shopify API question to confirm Codex searches the current docs.

Once installed, Codex gets access to Shopify documentation search, code validation against bundled API schemas, and the same skill set available to Claude Code and Cursor.

For the full breakdown of what the toolkit does, how it works, and the governance risks around store execution, see our Shopify AI Toolkit overview.

Why you can trust us

Jacques has over 15 years of development experience and has worked with hundreds of Shopify stores. We build Fudge, the AI operator for Shopify stores, with a 4.9 rating on the Shopify App Store and a Built for Shopify badge. We use these tools daily.

Prerequisites

• OpenAI Codex CLI installed and working
• Node.js 18 or higher, Shopify’s documented minimum (node --version to check). Node 18 reached end of life in April 2025, so use Node 20 LTS or newer
• Shopify CLI installed (needed for store operations)
• A Shopify store to connect to (only required for store operations)

Installation: plugin method

In your terminal, run Shopify’s documented command:

codex plugin add shopify@openai-curated

Or, inside the Codex CLI, run /plugins, search for Shopify, then select Add to Codex.

This installs the Shopify plugin with all available agent skills.

Verify installation

Ask Codex something Shopify-specific:

What's the correct GraphQL mutation to update a product's title in the Shopify Admin API?

If the toolkit is active, Codex will search current Shopify documentation and validate its output rather than guessing from training data.

Alternative: manual skills installation

If your setup can’t use the plugin, or you’d rather manage the skill yourself, install it directly:

npx skills add Shopify/shopify-ai-toolkit

This installs the toolkit’s single shopify skill, which covers every Shopify developer surface: the GraphQL Admin API, Shopify Functions, Polaris, Liquid, Hydrogen and Shopify CLI. Earlier versions shipped a separate skill per surface, such as shopify-admin and shopify-liquid. Those are deprecated and no longer updated, so if you installed any of them, remove them (for example npx skills remove shopify-admin shopify-liquid) and install the shopify skill instead.

Manually installed skills don’t auto-update. Run npx skills update periodically to stay current with Shopify’s API changes. Otherwise the bundled schemas drift from the live platform.

Alternative: MCP server setup

For direct MCP integration, Codex uses TOML configuration (unlike Cursor and Gemini CLI which use JSON). The Dev MCP server runs as a local server/client integration but makes network calls to Shopify endpoints for documentation search.

Add this to your ~/.codex/config.toml file, as given in the Shopify AI Toolkit docs:

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

Note the snake_case mcp_servers key, where JSON clients use mcpServers. Restart Codex to load the new configuration.

Telemetry and code transmission

Before you start validating code: both validate.mjs and search_docs.mjs send usage payloads to Shopify’s servers by default.

The SKILL.md files describe this as “anonymized validation results (pass/fail and skill name).” However, the actual validation payload includes the code being validated - your GraphQL queries, Liquid templates, and other code you run through the validator.

To opt out:

export OPT_OUT_INSTRUMENTATION=true

Set this before launching Codex if you’re working with proprietary or client code.

Connecting to your store

For store operations (not just code generation and validation), you authenticate through Shopify CLI:

shopify store auth --store yourstore.myshopify.com --scopes write_products,read_products

The toolkit detects minimum required scopes during validation. Common scopes:

Use the minimum scopes needed. write_products grants access to all product write operations, not just the specific mutation you’re running.

What you can do

The capabilities are the same across all supported AI clients. Here’s what the toolkit enables:

Validated GraphQL - Queries and mutations validated against the bundled Shopify API schema before you use them. Fewer hallucinated fields and deprecated patterns.

Theme development - Liquid templates validated against Shopify’s theme rules, including schema blocks and LiquidDoc headers.

Hydrogen storefronts - React component generation with validated imports and patterns.

Functions and extensions - Backend customization (discounts, cart validation, delivery rules) and UI extension scaffolding with Polaris components.

Store operations - Execute Admin GraphQL against a live store via shopify store execute --allow-mutations. Changes are immediate - there is no draft step. See our main guide for the full risk breakdown.

Metafield management - Extend your store’s data model with metafield definitions and custom data.

For hands-on theme examples, see How to Add Custom Liquid Logic in Shopify.

Best practices

These apply across all toolkit clients, but are worth repeating.

1. Query before you mutate. Always read the current state of a resource before updating it. This prevents unintended overwrites.

2. Be specific with mutations. “Optimize my products for SEO” is too vague. “Update the meta description for product handle ‘classic-tee’ to ’…’” is specific enough to be safe.

3. Push themes as unpublished. The toolkit supports shopify theme push --unpublished but doesn’t enforce it. Make it a habit.

4. One resource at a time for critical changes. Limits blast radius if something goes wrong.

5. Keep your own backups. The toolkit has no undo. Export current values before running mutations that update existing content.

Limitations

These are structural to the toolkit, not Codex-specific. For the full risk analysis, see our Shopify AI Toolkit overview.

1. No draft mode - Store mutations execute on your live store immediately
2. No preview - You can’t see what changes will look like before they happen
3. No undo/rollback - Changes are permanent once executed
4. No audit trail - No toolkit-level record of what was changed
5. Broad scopes - OAuth permissions apply to entire resource types, not individual items
6. Code sent to Shopify - Validation payloads include your code by default (opt out with OPT_OUT_INSTRUMENTATION=true)
7. Manual skills decay - Non-plugin installations need periodic manual updates

Where Fudge fits

The AI Toolkit makes you faster at writing Shopify code: schemas, themes, Hydrogen, custom apps. It is not the right surface for the merch team running daily ops, and it doesn’t add the workflow that real store changes need: drafts, previews, approvals, version history, rollbacks. Code lives in git; store state doesn’t.

That’s the gap Fudge, the AI operator for Shopify stores, fills. Instead of each person wiring Codex into the store and deciding what to change, your team gets a ready-made way to keep improving it: Fudge picks the work worth doing for a goal you choose, builds it as drafts in your theme, and your team previews, approves or rolls back each change.

Theme requests go through its store editor, and Codex stays useful for the custom code your developers write.

Quick reference

For the full picture on risks, read our Shopify AI Toolkit overview. For other platforms, see our Claude Code guide and Cursor guide.

We last re-verified the commands on this page against Shopify’s docs in October 2026.

FAQ