Wiring Claude/ChatGPT to Your Medusa Store via MCP

The short answer: build a small MCP server that wraps your Medusa store's REST or JS SDK, expose a handful of well-scoped tools (search products, check order status, look up inventory) rather than raw API passthrough, and register that server with Claude Desktop, Claude Code, or a ChatGPT custom connector using its stdio or HTTP transport. The result is an AI assistant that can answer real questions about your live catalog and orders, or safely trigger narrow actions, without you hand-rolling a bespoke chat integration for every model provider. The rest of this guide walks through the protocol, the server design, and the exact wiring steps for both Claude and ChatGPT.

What MCP Actually Is

Model Context Protocol is an open, JSON-RPC-based standard for connecting an AI model to external systems in a structured way. Instead of pasting API docs into a prompt and hoping the model formats requests correctly, you run a small server that advertises a fixed set of capabilities — resources (readable context, like a product catalog snapshot), tools (callable functions with typed input/output schemas, like "get order by id"), and prompts (reusable prompt templates the host can surface to the user). The model-facing client — Claude Desktop, Claude Code, or a ChatGPT connector — discovers those capabilities at connection time and decides when to call them mid-conversation.

The appeal for commerce is that MCP servers are provider-agnostic by design. Write one Medusa MCP server and it works the same way whether the client asking questions is Claude, ChatGPT, or any other MCP-compatible host — you are not maintaining a Claude-specific integration and a separate ChatGPT plugin. That matters more every quarter as the number of AI surfaces a merchant's team actually uses keeps growing: a support lead in Claude Desktop, a marketer in ChatGPT, an ops person driving Claude Code against staging data.

Why Medusa Is a Good MCP Fit

Medusa's modular architecture already separates commerce logic into well-defined modules — product, order, cart, inventory, pricing, promotion — each with a workflow-based API rather than a tangle of ORM calls. That separation maps cleanly onto MCP tools: a "search products" tool can call the product module's query layer directly, an "get order" tool can call the order module, and you never have to write a shim that reverse-engineers intent from a natural-language request the way you would against a less structured backend. If your team is already comfortable with Medusa's workflow and module conventions (see the medusa-engineering skill notes on query.graph and admin workflows if you maintain the backend), writing MCP tools is mostly a matter of wrapping existing service calls in a schema.

The Shape of a Medusa MCP Server

Resources vs. tools vs. prompts

Resist the temptation to expose everything as one giant tool. Resources are best for read-heavy, relatively static context — a store's shipping policy text, a category tree, a product catalog export the model can search over without a round trip per question. Tools are for anything parameterized or that changes state — "find products matching a query," "look up an order by id or email," "check inventory for a variant," "apply a discount code to a draft order." Prompts are optional templates you can ship alongside the server — for example a "draft a reply to this order-status inquiry" prompt that pre-fills the order-lookup tool call and asks for a specific tone.

A useful rule of thumb: if a human support agent would need to click into three different Medusa admin screens to answer a question, that is a sign that question should collapse into one purpose-built tool rather than three generic ones. A "get_order_status" tool that internally joins order, fulfillment, and payment state into one clean response is far more reliable in the model's hands than three separate low-level lookups it has to sequence and reason about itself.

Read tools first, write tools deliberately

Start with read-only tools: product search, order lookup, inventory checks, customer lookup by email. These carry essentially no downside risk and immediately make the assistant useful for support and merchandising questions. Only add write tools — creating a discount, updating an order note, cancelling a fulfillment — once you have decided exactly what guardrails they need, because an MCP tool is an API endpoint the model can call on its own initiative mid-conversation, not just when a human explicitly asks for that exact action in that exact moment.

Step by Step: Building a Minimal Medusa MCP Server

1. Scaffold the server

Use the official MCP TypeScript SDK to scaffold a server process. At minimum you need a server object registering your tools with a name, description, and a Zod (or JSON Schema) input schema, plus a transport — stdio for local desktop clients, or streamable HTTP if you want a remotely hosted server multiple teammates can point their clients at. For a first version, stdio is simplest: Claude Desktop and Claude Code both launch the server as a subprocess and speak MCP over its stdin/stdout, so there is no networking or auth layer to stand up yet.

2. Wrap Medusa's JS SDK or Admin API

Inside each tool handler, call Medusa's JS SDK (or the Admin/Store REST API directly) exactly as you would from any backend script. A product-search tool takes a free-text query and optional filters, calls the product module's list/query method, and returns a compact JSON shape — id, title, handle, price, inventory status — rather than the full raw Medusa product object, which is large and mostly irrelevant to the model's next step. Trimming response payloads to just what a model needs also meaningfully reduces token usage and latency on every tool call, which adds up across a long conversation.

3. Scope credentials per tool, not globally

Give the MCP server its own Medusa API key or admin user, scoped as narrowly as the tool set requires. If every tool you have shipped is read-only, that key should not have write permissions at all — a compromised or over-eager MCP client should not be able to do more damage than a support rep reading the admin dashboard. If you later add order-cancellation or discount-creation tools, consider a second, more privileged credential used only by those specific handlers, so a bug in a read tool can never accidentally exercise write scope it was never given.

4. Wire it into Claude Desktop or Claude Code

Claude Desktop reads MCP server definitions from its configuration file, where you register a command (the binary or script that starts your server) and any environment variables it needs, such as your Medusa base URL and API key. Restart Claude Desktop and the new tools appear in the tool picker for any conversation. Claude Code supports the same MCP servers through its own configuration, which is the more natural home for this if your team is already using Claude Code against the Medusa backend day to day — the same server can answer "what is the status of order 4021" in a chat and be invoked programmatically while an engineer is debugging a workflow.

5. Wire it into ChatGPT

ChatGPT connects to MCP servers over HTTP rather than stdio, through its connectors/actions configuration, which means your Medusa MCP server needs a network-reachable deployment — even a small always-on Node process behind a URL — rather than a local subprocess. The tool definitions and schemas you already wrote for the stdio version are reusable as-is; only the transport and the deployment target change. This is also the point where authentication stops being "whatever environment variable is on your laptop" and starts needing a real API key or OAuth flow in front of the server, since it is now reachable outside your machine.

Design Patterns for Commerce-Safe Tools

A few patterns consistently make MCP tools more reliable in front of a commerce backend, regardless of which model is calling them.

• Return structured, bounded results. Cap list results (top 10 matching products, not 400) and paginate explicitly rather than dumping an entire catalog into context.
• Make destructive tools require an explicit confirmation field in their input schema — for example a boolean "confirm: true" the model must set only after summarizing the action back to the user — so a single ambiguous instruction cannot silently cancel an order.
• Log every tool call server-side with the arguments and the acting session, exactly like you would log an API request from any other client, since an MCP tool is functionally a new API surface.
• Fail loudly and specifically. Return a clear error message ("no order found for that id") rather than a generic 500, so the model can relay something useful to the person it is helping instead of guessing.
• Version your tool schemas. Once a tool is in active use, changing its input shape breaks any saved prompts or automations built against it — treat the schema like a small public API contract.

Security and Guardrails

Treat an MCP server exactly as seriously as any other authenticated API you expose. Put write-capable tools behind their own credential, rate-limit the server the same way you would any public endpoint, and avoid ever handing the model a raw Medusa admin API key it could echo back into a response. If the server is HTTP-reachable for ChatGPT or a hosted Claude integration, run it behind normal request auth (an API key header or OAuth) — do not rely on obscurity of the URL. It is also worth deciding up front which tools are safe to expose to a customer-facing assistant versus an internal one; a "look up my own order" tool scoped to the authenticated customer's email is a very different risk profile from an admin-wide order-search tool, even though the underlying Medusa call is similar.

Where This Fits in a Headless Commerce Stack

MCP is a natural complement to a headless Medusa setup, not a replacement for your storefront. A Next.js storefront still owns the actual buying experience; the MCP server is a second, parallel interface into the same commerce backend for AI assistants, support tooling, and internal automation. Teams already running Medusa with a custom Next.js front end are well positioned here, since the module boundaries that make a clean storefront integration possible are the same ones that make clean MCP tools possible — the work is mostly wrapping, not restructuring. If you are still deciding on the storefront layer itself, that is a separate design conversation; our Figma UI kits cover the interface side of headless commerce builds, while this guide is specifically about the AI-agent wiring.

It is also worth being honest about maturity here: MCP tooling for commerce backends is genuinely new, and the ecosystem (client support, auth conventions, hosted-server patterns) is still settling. Start with a small, read-only tool set, watch how people actually use it, and expand deliberately rather than exposing your entire admin surface on day one.

Frequently Asked Questions

Do I need to modify my Medusa backend to add MCP support?

No. An MCP server is typically a separate small process that calls your existing Medusa Admin API, Store API, or JS SDK the same way any external client would. You are adding a new client, not changing Medusa itself.

Can the same MCP server work with both Claude and ChatGPT?

Yes, with one caveat: the tool definitions and logic are reusable, but the transport differs. Claude Desktop and Claude Code typically launch a local server over stdio, while ChatGPT connectors expect an HTTP-reachable server. Plan to support both transports if you want both clients working against the same tool set.

Is it safe to let an AI assistant cancel orders or issue refunds directly?

Only with real guardrails: a scoped credential limited to that action, an explicit confirmation step in the tool's input schema, and full logging of every call. Most teams are better served starting with read-only tools and adding narrowly-scoped write tools later, once they have seen how the assistant actually gets used in practice.

How is this different from just giving a model API documentation in the prompt?

Pasting API docs into a prompt relies on the model correctly formatting requests, handling auth, and parsing responses every single time, with no guarantees. MCP tools have typed schemas the client validates before calling, return structured data instead of raw API responses, and are discovered automatically by the host — it is the difference between describing an API and shipping one.