Medusa.js and AI Agents: How to Build Custom Commerce Faster in 2026

Most commerce platforms were never built to be operated by a coding agent. They assume a human engineer is sitting in front of a partner directory, writing glue code by hand, reading screenshots of admin screens. Put Claude Code or Cursor in front of one of those platforms and you feel the friction in the first ten minutes. Then try the same thing with Medusa.js v2. The experience flips. The agent reads the source, queries the docs through an official MCP server, and ships a real feature inside an afternoon.

If you are an engineering leader at a DACH or Nordic brand weighing a Shopify replacement, or a CTO trying to figure out where AI coding agents actually fit in your stack, this is for you. I have spent the last six months auditing four Medusa migrations and pairing the framework with Claude Code on three client projects. By the end of the post, you will know what Medusa.js v2 is, why it suits AI agents better than any commercial alternative I have tested, and how to wire the whole stack together in roughly five minutes. Want the install commands and configs upfront? Skip straight to the five-minute setup.

What Is Medusa.js v2 and Why It Matters in 2026

Medusa.js is an MIT-licensed, open-source headless commerce framework written in TypeScript. The v2 release, currently at version 2.15.3 as of June 2026, decouples seventeen commerce modules from a shared database schema and exposes Store, Admin, and Workflow APIs you build any frontend on. In practice, it is the most flexible commerce engine you can self-host today.

Three building blocks define how the framework is used.

The first is the Commerce Modules. Cart, Order, Product, Customer, Inventory, Payment, Promotion, Tax, and roughly nine more. Each module is isolated. Each module is replaceable. If you want to keep Cart but route Inventory through SAP, you can do that without rewriting the rest.

The second is the Framework itself, where custom logic lives. It is built around API Routes, Data Models, Module Links, and Workflows. The workflow engine is the underrated star of v2. Steps are atomic, each one carries a compensation function for automatic rollback, and you can hook into core workflows without forking them.

The third is the Admin Dashboard. A built-in React app you extend with widgets and UI routes. Internal supplier portals, custom reporting views, approval flows, all of it lives here without a separate frontend project.

The brands using Medusa in production matter too. Eight Sleep runs on it. So does INSPIRED Pet Nutrition, and Redington, India's largest IT distributor. This is not a side project anymore.

Why Medusa.js Works So Well With AI Coding Agents

Medusa is unusually well-suited to AI coding agents because its surface area is open, typed, predictable, and queryable through an official MCP server. That combination of four traits is rare in commercial commerce platforms, and it is the reason agent-assisted development feels smooth instead of frustrating.

Each of those traits earns its place individually.

Open source means the full codebase lives on GitHub. Claude Code reads the actual source when it gets stuck. It does not have to guess from documentation that may be out of date.

TypeScript and Node.js are two of the most heavily represented languages in any model's training data. Type signatures act as a guardrail. The moment the agent hallucinates a method, the compiler shouts.

Predictable patterns mean every API route lives at src/api/<path>/route.ts, every workflow is a series of createStep calls, every admin widget is a default-exported React component plus a defineWidgetConfig block. The agent does not invent structure, it follows it.

AI-friendly documentation means every page on docs.medusajs.com ships with a markdown export and is exposed through an MCP endpoint. The agent queries the docs directly.

A short story to make this concrete. Last March I was helping a Hamburg fashion brand evaluate Medusa against a Shopify Plus extension build. Their CTO, Lena Albrecht, gave us four hours to prototype a custom care-instructions field that needed to surface in the admin, the storefront, and a downstream PIM. Their Shopify partner had quoted six weeks. With Medusa and Claude Code, we shipped a working prototype (data model, migration, admin widget, store route) in under three hours of pair programming. The agent did roughly 70% of the typing. Lena's verdict afterwards: "I thought the magic was the AI. The magic is that the framework lets the AI do its job."

That is the core argument. Medusa is not winning on flashier AI features. It is winning because its architecture rewards the structured, pattern-following work that agents are actually good at.

The Medusa AI Tooling Stack at a Glance

The Medusa AI tooling stack is the official set of integrations Medusa ships for AI-assisted development. It includes a remote MCP server, a Claude Code plugin marketplace, a terminal-native Cloud CLI, a Cloud Development Agent for debugging, and Bloom, a chat assistant for operating the store. Each piece is designed to be invoked by another AI tool, not just by a human.

The Medusa MCP Server

The Medusa MCP Remote Server is a Streamable HTTP endpoint at https://docs.medusajs.com/mcp. Any MCP-compatible client (Claude Code, Cursor, VS Code, Windsurf) connects to it and gets live access to the full Medusa documentation. The server is gated to Medusa Cloud users and supports OAuth or a personal access token.

For Cursor, the config sits in .cursor/mcp.json:

{
  "mcpServers": {
    "medusa": {
      "url": "https://docs.medusajs.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Once it is connected, the agent stops working from stale training data. Ask it how to add a hook to the createCartWorkflow, and it queries the actual reference and writes code against the current API.

New to the protocol itself? I broke down how skills, MCP, and plugins layer together in the agent stack in a separate post — Medusa's MCP server is a textbook example of the connectivity layer done right.

Medusa Agent Skills

medusajs/medusa-agent-skills is the official Claude Code plugin marketplace for Medusa. As of release 1.0.7 in February 2026, it ships four plugins.

medusa-dev covers backend, admin, and storefront development skills. learn-medusa is an interactive tutorial where Claude acts as your instructor. ecommerce-storefront ships high-converting storefront patterns. medusa-cloud drives the Cloud CLI from inside the agent.

Two commands inside Claude Code installs the lot:

/plugin marketplace add medusajs/medusa-agent-skills
/plugin install medusa-dev@medusa

Medusa Cloud CLI and Development Agent

The Medusa Cloud CLI (@medusajs/mcloud) makes deployment, build logs, runtime logs, and environment context callable from a terminal. It is built to be invoked by your coding agent. Claude Code runs mcloud logs --search "OrderPlacedHandler" --source backend, streams the output, and reasons about what broke without you opening a dashboard.

Paired with it is the Cloud Development Agent. An infrastructure-aware teammate that already knows your project, deployments, and environment variables. When a production deploy fails, you ask the agent to investigate and it pulls the relevant context for you.

Bloom and AI-Friendly Documentation

Bloom is Medusa's first-party commerce assistant. It is aimed at store operators, not developers, but it signals where the platform is going: agents that run your store, not just build it. The AI-friendly docs layer underneath is the quiet hero. It is the reason the MCP server works as well as it does.

Want the full setup walkthrough in one place? The five terminal commands in the next section get you connected end to end.

How to Connect Cursor or Claude Code to Medusa in Five Minutes

The fastest path from zero to a working Medusa + AI agent setup is five terminal commands. You bootstrap the project, install Claude Code, attach the official plugins, and verify the MCP connection.

Run this sequence:

# 1. Create the Medusa project
npx create-medusa-app@latest my-store
cd my-store

# 2. Start Medusa (keep this terminal running)
npm run dev

# 3. In a second terminal, install Claude Code and launch it
npm install -g @anthropic-ai/claude-code
claude

# 4. Inside Claude Code, attach the Medusa plugins
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install medusa-dev@medusa

# 5. Verify
/plugin

The /plugin command should list medusa-dev under Installed. Send the agent a quick prompt, something like "describe the project structure," and confirm the reply references src/modules, src/workflows, src/api, and src/admin. If it does, the MCP connection is live and you are ready to build.

For Cursor, the path is slightly different. Drop the .cursor/mcp.json config above into your project root, then run yarn skills add medusajs/medusa-agent-skills to copy the skill markdown into .cursor/skills/. Same end state.

Building a Custom Feature With Medusa.js and Claude Code: A Walkthrough

Building a custom feature with Medusa.js and Claude Code follows a four-step pattern: extend the data model, scaffold the admin surface, write the workflow, and verify the diff. The agent does most of the typing. Your job is to specify the behavior clearly and review the output — and that review discipline matters more than the framework choice. It is the same thing that separates the agent projects that survive production from the 91% that don't.

Let me walk through a real example. In April 2026 I worked with Erik Holm, lead engineer at a Stockholm-based outdoor-apparel brand selling through three channels: DTC web, Amazon, and a B2B distributor portal. He needed a supplier_email field on each product so order fulfillment could notify the right warehouse automatically. With their previous Shopify Plus setup, the equivalent build had taken a partner agency seven weeks. With Medusa and Claude Code it took two working days, and most of that was reviewing code and writing tests.

The conversation with Claude Code looked roughly like this:

Add a supplier_email field to the Product data model. Make it editable in the admin product detail page, exposed on the Store API as a read field, and used in a new workflow that triggers on order.fulfilled and sends a notification per supplier with the relevant line items. Use the Notification module abstraction.

What the agent produced:

A module link extending the Product module with the new field, plus the migration. An admin widget at the right injection zone on the product detail page. A subscriber for the order.fulfilled event. A workflow with three createStep calls (fetch products and supplier emails, group line items per supplier, send notifications), each with its own compensation function.

I read the diff, asked the agent to add a test for the workflow's compensation path, and we pushed. The whole loop took an afternoon. If you want a second pair of eyes on a similar build, I run free 30-minute Medusa architecture reviews for teams who are evaluating the stack.

When Medusa.js + AI Agents Pays Off (and When It Does Not)

Medusa.js paired with AI coding agents pays off when you need real customization that off-the-shelf SaaS commerce platforms cannot deliver economically. It is overkill for a small DTC store with under a hundred SKUs and a basic Stripe checkout. The honest middle ground is where it gets interesting: mid-market brands that have outgrown Shopify Plus and are evaluating commercetools or a custom build.

Three patterns I keep seeing in audits.

The first is B2B portals with company hierarchies. In Q1 2026 I worked with Markus Bauer, CTO at a Munich industrial-supplies distributor that needed company-level pricing, approval workflows, and quote-to-order conversion. Medusa's first-class B2B recipe paired with Claude Code shipped the MVP in eleven weeks, against a six-month estimate from a commercetools partner. His decision wasn't about love for open source. It was about timing.

The second is multi-region commerce with strict data residency. GDPR posture and EU data sovereignty are easier with a stack you actually host. For Nordic and DACH clients in finance-adjacent verticals, this is often the deciding factor. Self-hosting Medusa in Hetzner Cloud Frankfurt is a much cleaner conversation with procurement than negotiating data processing addendums with a US SaaS vendor.

The third is commerce-as-workflow over an existing ERP. When SAP or Microsoft Dynamics already owns inventory and pricing, Medusa becomes the orchestration layer in front. The Workflow engine handles the choreography. Claude Code writes the SAP integration steps faster than any human team I have worked with — though getting those agent workflows reliable in production is still on you, not the framework.

A note of honesty here. The Medusa AI tooling is still maturing. The MCP server's OAuth flow can be flaky on the first connection, and we had to fall back to a personal access token twice in May. The Cloud CLI occasionally lags on log streaming during high-traffic deploys. The agent skills repository is on release 1.0.7, which means rough edges. I am still recommending this stack because the architecture is right and the team is shipping fast, but I would be lying if I said it is as polished as Shopify's admin. It is not. It is, however, heading somewhere Shopify cannot follow without rebuilding from scratch.

The Bottom Line

Medusa.js v2 is the most agent-native commerce framework on the market in 2026. The architecture rewards the structured work AI coding agents are good at, and the official tooling (MCP server, Claude Code plugins, Cloud CLI, Development Agent) collapses the cost gap between SaaS commerce and a custom build by roughly an order of magnitude. The trade-off is real, though. The stack pays off for mid-market and enterprise brands with actual customization needs, not for small DTC stores selling a handful of SKUs. Be honest about where you sit before you commit.

If you are evaluating Medusa for a 2026 build or migration and want a second opinion before you sign anything, book a free 30-minute architecture review. No slide deck, no sales pitch. Just a working engineer's read on whether the stack fits your problem.

Pawel Owerczuk is a freelance AI and full-stack engineering consultant based in Poland, working with DACH and Nordic enterprises on AI-augmented product development. Read more on my blog or learn about my consulting services.

Sources

• Medusa Documentation: Build with AI Assistants and LLMs
• Medusa Documentation: MCP Remote Server
• Medusa Documentation: Agent Skills
• Medusa v2 Overview
• Medusa Cloud CLI and Cloud Development Agent
• How to Build a Custom Ecommerce Store with Medusa and Claude Code
• medusajs/medusa-agent-skills on GitHub
• Anthropic: Claude Code Documentation
• Model Context Protocol Specification