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 your Medusa applications deployed on Cloud. MCP is an open standard that AI tools use to connect to external data and services.

The AI tool can access:

• Commerce data: Orders, products, customers, and other data from your store's Admin and Store API routes.
• Custom data: Data from your own custom API routes, such as data from your custom modules.
• Cloud data: Your organizations, projects, deployments, logs, and environment variables.

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?"
• "Which carts were abandoned in the last 24 hours?", answered by a custom API route.
• "Why did my latest deployment fail? Check its build logs."
• "Show me the errors in my backend's logs from the last hour."

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

The Medusa MCP is available for all Cloud plans.

Connect to the Medusa MCP Server#

This section explains how to connect your AI tool to the Medusa MCP server.

Prerequisites#

Step 1: Rebuild Environments#

Medusa indexes an environment's API routes when the environment builds. Environments built on or after October 8, 2026 are already indexed, so you can skip to connecting an AI tool.

If the environment's latest build is from before October 8, 2026, rebuild it so that Medusa indexes its API routes.

To rebuild an environment:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment.
3. 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 2: Connect an AI Tool#

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

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

Add the Claude Connector from Claude's connectors directory.

Claude Code

Run the following command in your terminal:

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

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

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:

{
  "mcpServers": {
    "medusa-commerce": {
      "url": "https://cloud.medusajs.com/mcp"
    }
  }
}

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

VS Code

These steps also apply to GitHub Copilot in VS Code, since Copilot's agent mode uses the MCP servers that you configure in VS Code.

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

{
  "servers": {
    "medusa-commerce": {
      "type": "http",
      "url": "https://cloud.medusajs.com/mcp"
    }
  }
}

When you start the server, VS Code prompts you to log in to your Cloud account. Then, open the Copilot Chat view in agent mode to use the Medusa MCP server's tools.

Codex

Run the following commands in your 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:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "medusa-commerce": {
      "type": "remote",
      "url": "https://cloud.medusajs.com/mcp"
    }
  }
}

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

opencode mcp auth medusa-commerce

Gemini CLI

Install the Medusa extension for Gemini CLI, which adds the Medusa MCP server to Gemini CLI:

gemini extensions install \
  https://github.com/medusajs/gemini-cli-extension

Then, start Gemini CLI and run the following command to log in to your Cloud account:

gemini
/mcp auth medusa

n8n

Add an MCP Client Tool to an AI Agent node in n8n Cloud, as explained in the n8n guide. Self-hosted n8n instances can't connect to the Medusa MCP server.

Custom Agents

To connect an agent that you build yourself, follow the Connect a Custom Agent guide.

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.

1. Select the environments that the AI tool can access.
2. Click Approve.

If you don't have any environments to select, click the Create Project button on the consent page. It opens the project creation page in a new tab. After you create a project, return to the consent page to select its environment and approve the connection.

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, change the connection's environments from your organization's Connections settings. Alternatively, re-authenticate the AI tool with the Medusa MCP server and select the environments again on the consent page.

To disconnect an AI tool, revoke its connection from your organization's Connections settings, or 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. Learn more in the Custom API Routes section.
• Read Cloud data: Retrieve the details of your organizations and projects, list an environment's deployments, read an environment's build and runtime logs, and inspect its environment variables. Learn more in the Cloud Tools section.
• Check Cloud status: Check whether Cloud is operational or has an ongoing incident.
• 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 stores and from Cloud, 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.
• If you ask the AI tool to redeploy an environment or change an environment variable, it explains that it can't. Use the Cloud dashboard or the Cloud CLI instead.

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.

Commerce Tools#

The AI tool uses these tools to retrieve data from your stores, including data from your custom API routes.

Cloud Tools#

The AI tool uses these tools to retrieve data about your organizations, projects, and environments on Cloud. For example, you can ask the AI tool:

• "Why did the latest deployment of my production environment fail?"
• "Show me the errors in my backend's runtime logs from the last hour."
• "Which environment variables are set in my staging environment?"
• "Is Cloud having an incident right now?"

The AI tool can only access the organizations, projects, and environments that you connected to it.

Documentation and Feedback Tools#

The AI tool uses these tools to answer general questions about Medusa and to share your feedback with the Medusa team.

Custom API Routes#

The AI tool isn't limited to Medusa's API routes. It can also find and call your store's custom GET API routes, so you can ask it questions about any data that your store has, such as:

• Data in your custom modules, such as brands, suppliers, or loyalty points.
• Reports that Medusa's API routes don't provide, such as abandoned carts or products that haven't sold in the last month.
• Data from third-party systems that your Medusa application integrates with, such as an ERP or a CMS.

Medusa indexes a store's API routes, including its custom API routes, each time the environment builds. Medusa reads each custom API route's comments and TypeScript types to describe the API route to the AI tool. So, the AI tool can find and call your custom API routes after you deploy them, without extra configuration.

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, or API routes defined in plugins.

To learn how to create custom API routes that the AI tool can find and use, and the best practices to write them, refer to the Retrieve Custom Data guide.

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 and projects. 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#

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 the environment's latest build is from October 8, 2026 or later. Otherwise, rebuild the environment. Redeploying an existing deployment doesn't index the environment's API routes.

Store Login Errors#

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.