Help

Medusa MCP

In this guide, you'll learn how to connect AI tools like Claude, ChatGPT, and Cursor to your Cloud stores with the Medusa MCP server, and what they can do once connected.

What is the Medusa MCP Server?#

The Medusa MCP server is a remote Model Context Protocol (MCP) server that gives AI tools access to the commerce data of your Medusa applications deployed on Cloud. MCP is an open standard that AI tools use to connect to external data and services.

Once you connect an AI tool to the Medusa MCP server, you can ask it questions about your stores in natural language, such as:

"Show me the 5 most recent orders in my store, with each order's total and status."
"How many orders are waiting to be fulfilled?"
"What products are available to shoppers in my B2B sales channel?"

Your AI tool then retrieves the relevant data from your store and presents it to you in a human-readable format.

Connect to the Medusa MCP Server#

This section explains how to get access to the Medusa MCP server and connect your AI tool to it.

Prerequisites#

Cloud account↗Environment with a live deployment↗Medusa v2.12.4+ in the environment's Medusa application↗

Step 1: Request Access#

The Medusa MCP server is in early access. To request access for your organization, email support@medusajs.com with the name of your organization.

If your organization already has access, skip to the next step.

Step 2: Rebuild Environments#

After Medusa informs you that your organization has access, rebuild each environment that you want to connect to the Medusa MCP server.

Warning: You must start a new build of the environment. Redeploying an existing deployment reuses its previous build, so Medusa doesn't index the environment's API routes.

To rebuild an environment:

If you're in a different organization, switch to the organization.
Click Projects in the sidebar and select the project that contains the environment.
Select the environment, then click Trigger build at the top right of the page.

You can also start a new build with the Cloud CLI's mcloud environments trigger-build command.

Once the build finishes and the deployment is live, you can connect the environment to your AI tool.

Step 3: Connect an AI Tool#

The Medusa MCP server is a Streamable HTTP server at the following URL:

Code
https://cloud.medusajs.com/mcp

The Medusa MCP server authenticates with OAuth, so you don't need to create an access key. When you connect, the AI tool opens a browser window where you log in to your Cloud account and approve the connection.

Claude

The Claude Connector is coming soon to Claude's connectors directory. In the meantime, add the Medusa MCP server as a custom connector, as explained in the Claude Connector guide.

Claude Code

Run the following command in your terminal:

Terminal
❯claude mcp add --transport http medusa-commerce \❯  https://cloud.medusajs.com/mcp

Then, start Claude Code and run the /mcp command:

Terminal
❯claude❯/mcp

Select the medusa-commerce server and choose Authenticate.

ChatGPT

The ChatGPT app is under review by OpenAI. In the meantime, add the Medusa MCP server as a custom plugin in ChatGPT's developer mode, as explained in the ChatGPT app guide.

Cursor

Add the following to your .cursor/mcp.json file or Cursor settings, as explained in the Cursor documentation:

.cursor/mcp.json
1{2  "mcpServers": {3    "medusa-commerce": {4      "url": "https://cloud.medusajs.com/mcp"5    }6  }7}

Then, open Settings > Tools & MCPs and click Connect next to the medusa-commerce server.

VS Code

Add the following to the .vscode/mcp.json file in your workspace:

.vscode/mcp.json
1{2  "servers": {3    "medusa-commerce": {4      "type": "http",5      "url": "https://cloud.medusajs.com/mcp"6    }7  }8}

When you start the server, VS Code prompts you to log in to your Cloud account.

Codex

Run the following commands in your terminal:

Terminal
❯codex mcp add medusa-commerce \❯  --url https://cloud.medusajs.com/mcp❯codex mcp login medusa-commerce

OpenCode

Add the following to your OpenCode config file, for example, ~/.config/opencode/opencode.json:

~/.config/opencode/opencode.json
1{2  "$schema": "https://opencode.ai/config.json",3  "mcp": {4    "medusa-commerce": {5      "type": "remote",6      "url": "https://cloud.medusajs.com/mcp"7    }8  }9}

Then, run the following command to log in to your Cloud account:

Terminal
❯opencode mcp auth medusa-commerce

Approve the Connection

After you log in to your Cloud account, Cloud shows a consent page with the AI tool's name and the access it requests.

Select the environments that the AI tool can access. You can only select environments in organizations that have Medusa MCP access.
Click Approve.

Warning: Only approve the connection if you started it yourself. Once approved, the AI tool can read data in the selected stores as you.

Once you approve the connection, return to your AI tool and start asking questions about your stores.

Manage Connected Stores#

To connect more stores or remove stores from an AI tool, re-authenticate the AI tool with the Medusa MCP server and select the environments again on the consent page.

To disconnect an AI tool, remove the MCP server or connector from the AI tool.

Confirm Your Identity#

If a store requires multi-factor authentication, the AI tool asks you to confirm your identity when it calls a tool that accesses the store's data, such as read_admin_api. Connecting the AI tool doesn't require this confirmation. The AI tool either opens a confirmation page in your browser or shows you its link.

After you confirm your identity, return to the AI tool and run the request again.

Medusa MCP Features#

Connect to environments: Connect the AI tool to one or more environments across your organizations, and choose which ones it can access. When you connect multiple environments, mention the store you mean in your question.
Read store data: Retrieve orders, products, customers, inventory, and other commerce data from your store's Admin API routes as your admin user. The AI tool can also retrieve storefront data, such as the products available in a sales channel, from your store's Store API routes as a guest customer.
Read custom store data: Retrieve data from your store's custom GET API routes under the /store and /admin prefixes. Medusa indexes your store's API routes each time the environment builds, so the AI tool finds new custom routes after you deploy them.
Answer Medusa questions: Search the Medusa documentation to answer general questions about Medusa.

Read-Only Access#

The Medusa MCP server is read-only. The AI tool can retrieve data from your store's Admin and Store API routes, but it can't create, update, or delete data. For example, if you ask the AI tool to cancel an order, it explains that it can't and points you to the Medusa Admin.

The AI tool calls Store API routes as a guest customer, so it can't access routes that require a logged-in customer.

Available Tools#

The Medusa MCP server provides the following tools to AI tools. You don't call these tools directly. The AI tool chooses which tools to call based on your question.

Tool	Description
`list_connected_environments`	Lists the environments that you connected to the AI tool.
`find_commerce_api`	Searches a store's Admin and Store API routes, including its custom API routes, for routes that retrieve the requested data.
`describe_commerce_api`	Retrieves the parameters and details of a store's API route.
`read_admin_api`	Sends a `GET` request to a store's Admin API route as your admin user.
`list_medusa_publishable_keys`	Lists a store's publishable API keys and their sales channels.
`read_store_api`	Sends a `GET` request to a store's Store API route as a guest customer, scoped to a publishable API key's sales channels.
`ask_medusa_question`	Searches the Medusa documentation to answer a question.
`submit_medusa_feedback`	Sends your feedback to the Medusa team. The AI tool only sends feedback when you ask it to, or after you approve the message.

Custom API Routes#

Medusa indexes a store's API routes, including its custom API routes, each time the environment builds. So, the AI tool can find and call your custom GET API routes after you deploy them.

Medusa only indexes custom API routes under the /store and /admin prefixes. The AI tool can't find or call custom API routes under other prefixes.

Medusa MCP vs Docs MCP#

Medusa provides two MCP servers:

The Medusa MCP server, at https://cloud.medusajs.com/mcp, reads data from your Cloud stores. It's the server this guide covers.
The Docs MCP server, at https://docs.medusajs.com/mcp, answers development questions from the Medusa documentation and provides implementation guides.

The Medusa MCP server can also search the Medusa documentation, so you don't need both servers to ask general Medusa questions. If you're writing code for your Medusa application, use the Docs MCP server for its implementation guides.

Troubleshooting#

Medusa MCP Isn't Enabled for Your Account#

If the AI tool shows an error that Medusa MCP isn't enabled for your account, none of your organizations have Medusa MCP access. Request access for your organization.

AI Tool Can't Find Your Store's API Routes#

If the AI tool can't find your store's API routes, including your custom API routes, make sure that you rebuilt the environment after your organization received access. Redeploying an existing deployment doesn't index the environment's API routes.

The Medusa MCP server logs in to your store with your Cloud account. If the AI tool shows an error that the store's Cloud login is disabled or misconfigured, make sure that:

The store's Medusa application uses Medusa v2.12.4 or later.
The environment has a live deployment.
You can log in to the store's Medusa Admin with the Log in with Medusa Cloud button, as explained in the Access Deployment guide.

Was this guide helpful?