---
title: "Your Custom Code Instantly Agent-Ready: How We Built the Medusa MCP"
description: "Discover how the Medusa MCP server uses generic API tools, searchable OpenAPI specs, and TypeScript-based route discovery to make every core and custom commerce operation instantly agent-ready."
url: https://medusajs.com/blog/how-we-built-the-medusa-mcp
last_updated: 2026-10-21T14:55:19Z
---

# Your Custom Code Instantly Agent-Ready: How We Built the Medusa MCP

_Published 2026-07-21 by Shahed  Nasser in Product_

Yesterday, we [announced the Medusa MCP](https://medusajs.com/blog/announcing-medusa-mcp): a remote MCP server that brings your data to your agents. The MCP makes your operations and development more efficient; it integrates into your daily agentic workflows to pull your data, create sales reports, investigate failing deployments, and more.

The Medusa MCP doesn't just work with Medusa's core data models and workflows. It also supports your business logic and functionality out of the box. From subscriptions to analytics to integrated CMS platforms, anything you expose through an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes) can be accessed from the MCP server.

This post dives into the technical details of how we accomplished this setup.

## Limitations in the Conventional Approach to MCP Servers

Most commerce platforms that offer MCP servers provide specific tools for each commerce operation. For example, a `read_product` tool to retrieve a product's information, and a separate `create_cart` tool for creating a cart.

While this approach does the job, there are a few limitations to it:

1. **Tool limits**: MCP clients have a limit on the number of tools accepted from an MCP server. For example, VS Code accepts 128 tools, whereas Cursor accepts 40 tools. So, these MCP servers would have to compromise the availability of some commerce operations in favor of others, even if they're relevant to your use case.
2. **Custom Tools:** You don't have a way to add tools for your own business logic and features, or, if you do, you have to take on the burden of implementing and maintaining these tools. The MCP server becomes a generic tool rather than a bespoke one tailored for your store.
3. **Version Control:** For open source platforms or platforms where you are responsible for your application's version, the MCP server's tools may not work with older versions due to their rigid implementation.

When we set out to build the Medusa MCP, our goal wasn't only to provide these commerce operations through an MCP server, but to solve these problems for our users. Our users get an MCP server that works with their store data and supports any of their use cases.

## Two Tools for Every API Route

Instead of dedicated tools for every core commerce operation, the Medusa MCP has the following generic tools to access your store's data:

1. `read_admin_api`: Perform a read operation on any API route that starts with the [`/admin`](https://docs.medusajs.com/api/admin) prefix.
   1. The tool handles the underlying authentication needed to access the route as an administrator. So, you don't need to pass any credentials or secrets to the agent, and the authentication is secure.
2. `read_store_api`: Perform a read operation on any API route that starts with the [`/store`](https://docs.medusajs.com/api/store) prefix. It handles passing the necessary headers like the [publishable API key](https://docs.medusajs.com/api/store/publishable-api-key) of your store.

So, when you ask your agent to read order data (core Medusa functionality) or check active subscriptions (your store's functionality), it uses the relevant tool above to send a request to `/admin/orders` or `/admin/subscriptions` and present the necessary data to you.

> Write operations are also coming soon to the MCP server.

But how does the agent know what API routes are available, especially custom ones implemented in your store, or the routes available to your Medusa version? These are the second and third limitations that the Medusa MCP solves.

## Searchable OpenAPI Spec Documents

[Medusa Cloud](https://medusajs.com/cloud) stores the API routes of an environment, including the core and custom routes, as a [Medusa Search](https://medusajs.com/blog/announcing-medusa-search) index. Medusa transforms an environment's OpenAPI Specs (OAS) into records in the search index.

> **What is an [OpenAPI Spec](https://spec.openapis.org/oas/latest.html)?** An OpenAPI Spec is a standard document for describing HTTP and REST APIs. It's typically used for documentation purposes to inform what a set of APIs do and how they can be consumed.

Each search index record holds information like the API route's method, description of what it does, and the required path, query, and request parameters.

Then, the Medusa MCP exposes the following tools:

1. `find_commerce_api`: Search through the OAS records of the user's environment to find the top 10 most relevant API routes for a query. For example, the agent can search for keywords like `list orders` or `get subscription` and the tool returns the API routes that could be a good fit.
2. `describe_commerce_api`: Retrieve all details about a specific API route, including what parameters it expects.

So, when an agent wants to perform a commerce operation on your behalf, it uses the tools in this order:

![](https://assets.medusajs.com/uploads/2026/10/searchable-openapi-spec-flow-1x-2-phsazeha.webp)

1. `find_commerce_api` to find the most fitting API route for the use case.
2. `describe_commerce_api` to see the full details of the selected API route.
3. `read_admin_api` or `read_store_api` to send the request to the API route with the required parameters.

This works not only with the Medusa core API routes that we already have OAS for, but also with the API routes you define in your project's source code. So, how do we discover your API routes and store them as part of the same search index?

## Custom API Route Discovery

As part of building your project for a new deployment on Medusa Cloud, we discover the API routes available to your store.

For core API routes, we identify the version of your Medusa application, then retrieve the OAS that we host for that version as part of our API reference. The documentation endpoint [https://docs.medusajs.com/api/versions](https://docs.medusajs.com/api/versions) returns all Medusa versions that we store an OAS document for, with the URL to retrieve it.

For your custom API routes, we use the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to discover and transform them into OAS. We do the following during your application's build:

1. Find all API route files under the `src/api/admin` and `src/api/store` directories of your Medusa application.
2. For each file, we: 
   1. Traverse its Abstract Syntax Tree (AST) to find route handler functions. These are the functions that define the API routes, such as `GET` and `POST` functions.
   2. Extract request and response types passed as type arguments to `MedusaRequest` and `MedusaResponse`, if available.
   3. Generate an OAS operation for the API route, including the expected request parameters and keywords relevant for your API route.
3. Combine the core OAS and the generated operations of the custom API routes into a single OAS document.

Then, we ingest all OAS document operations as records in the search index, allowing your agent to find and access them with the tools that the MCP server exposes.

![](https://assets.medusajs.com/uploads/2026/10/custom-api-route-discovery-1x-1-55jlpk7y.webp)

## Medusa MCP: No Limitations on Your Commerce Operations

With this implementation, the Medusa MCP solves the three limitations that conventional approaches to MCP servers impose:

![](https://assets.medusajs.com/uploads/2026/10/limitations-of-conventional-mcp-servers-1x-1-pexpzzn0.webp)

1. No tool limits to consider. Read operations are consolidated into two tools, and the same applies to write operations. We don't have to compromise the availability of a commerce functionality through the MCP server.
2. Custom API routes and workflows are handled as part of the read and write tools, similar to core data. You also don't have to maintain the implementation: access from the MCP server to these routes is available out of the box when you deploy to Medusa Cloud.
3. Medusa provides your agent with the relevant OAS and available routes for your Medusa application's version. You can use the Medusa MCP with any Medusa version.

## Get Started with Medusa Cloud

To start using the Medusa MCP, get started with [Medusa Cloud](https://cloud.medusajs.com/) and deploy your project. You can then start managing it with your AI agent.

Refer to the documentation for more details on the [Medusa MCP](https://docs.medusajs.com/cloud/medusa-mcp).