Connect Medusa to Claude: Manage catalogs and complex order flows

If your team needs to connect Medusa to Claude to automate wholesale B2B ordering, execute complex RMA (Return Merchandise Authorization) workflows, or manage distributed inventory across multiple warehouses, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Medusa's deeply decoupled REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Medusa to ChatGPT or explore our broader architectural overview on connecting Medusa to AI Agents.

Giving a Large Language Model (LLM) read and write access to an advanced, highly relational commerce engine like Medusa is an engineering challenge. Medusa's architecture requires chaining multiple stateful API requests together to execute seemingly simple operations. Every time Medusa updates an endpoint or alters a promotion rule schema, a custom-built MCP server requires code changes, redeployment, and rigorous testing.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Medusa, connect it natively to Claude Desktop, and execute complex e-commerce workflows using natural language.

The Engineering Reality of the Medusa API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Medusa's Admin APIs is uniquely painful. Medusa is built for extreme flexibility, meaning data domains that are typically combined in older e-commerce platforms are explicitly decoupled here.

If you decide to build a custom Medusa MCP server, here are the specific integration challenges you will face:

The Order Edit State Machine In a simple e-commerce API, updating an order usually requires a single PATCH /orders/:id request. Medusa does not work this way. To safely mutate an order without breaking financial ledgers or tax lines, Medusa uses an "Order Edit" workflow. To add an item to an order, an LLM must first create an order edit, add a line item (which creates an ITEM_ADD action), request the edit, and then explicitly confirm it. This multi-step state machine is notoriously difficult for LLMs to navigate without strictly constrained, well-documented schemas.

Decoupled Inventory and Product Catalogs Medusa separates the concept of a Product Variant from its physical Inventory Level. An LLM cannot just "update stock to 50" on a product. It must identify the specific Product Variant, locate its associated Inventory Item ID, identify the specific Stock Location ID, and then update the Inventory Level at that location. This requires orchestrating 3-4 separate endpoints just to adjust stock for a single SKU.

Complex Pricing and Tax Regimes Prices in Medusa are managed via Price Lists and Price Preferences, entirely separated from the core product schema. This allows for complex B2B pricing, currency overrides, and customer-group specific rules. If an LLM needs to adjust pricing for a flash sale, it must interact with the Price List API, not the Product API.

Building an MCP server requires writing custom middleware to handle all of this relational mapping. Truto abstracts this away by dynamically generating tool definitions directly from Medusa's resource documentation, providing Claude with the exact JSON schemas and parameter descriptions it needs to navigate these decoupled domains.

Setting up the Medusa MCP Server

Truto eliminates the need to build a custom proxy. Because Truto already understands Medusa's authentication lifecycle and API architecture, it can dynamically generate a secure JSON-RPC 2.0 endpoint that serves Medusa endpoints as ready-to-use MCP tools.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Medusa account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your configuration. You can filter the tools by method (e.g., read-only) or by tags (e.g., only expose 'orders' and 'inventory').
5. Copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/<secure_token>).

Method 2: Via the Truto API

For platform builders deploying AI agents programmatically, you can generate MCP servers on the fly via the Truto API.

curl -X POST https://api.truto.one/integrated-account/<medusa_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medusa Order Ops MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["orders", "inventory", "products"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API responds with the tokenized URL that Claude needs to connect. The token securely encodes the specific Medusa tenant and the filter configuration - no further authentication configuration is required on the client side.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, providing Claude with access to Medusa takes seconds.

Method A: Via the Claude UI

If you are using an Enterprise or Pro tier with custom connector support:

1. Open Claude Settings.
2. Navigate to Integrations or Connectors.
3. Click Add MCP Server.
4. Paste the Truto MCP URL and click Add.

Claude will immediately ping the endpoint, execute the initialization handshake, and list the available Medusa tools.

Method B: Via manual configuration file

For Claude Desktop users or developers building custom infrastructure, you can add the server via the claude_desktop_config.json file. Truto's endpoints support Server-Sent Events (SSE), which the official MCP CLI tool can bridge seamlessly.

{
  "mcpServers": {
    "medusa-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<your_secure_token>"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The Medusa tools will appear instantly.

Hero Tools for Medusa Automation

Truto exposes the entirety of the Medusa API, but certain operations are particularly high-leverage for AI agents. Here are the hero tools that make Claude an effective B2B commerce assistant.

List All Products (list_all_medusa_products)

The foundation of any catalog workflow. This tool allows Claude to retrieve product data, variants, and relational IDs required for downstream pricing or inventory adjustments.

"Claude, pull the current product catalog and filter for items in the 'Winter Collection'. Return their IDs and base variant IDs."

Create a Draft Order (create_a_medusa_draft_order)

Essential for B2B wholesale scenarios. Draft orders allow an agent to build a cart without triggering immediate payment capture or fulfillment workflows.

"A B2B wholesale client requested 50 units of variant ID 12345. Create a draft order for their customer account, set the shipping address to their primary location, and leave the order in draft status for manual sales review."

Confirm Draft Order Edit (medusa_draft_orders_confirm_edit)

Because Medusa uses strict state machines for order mutations, Claude uses this tool to finalize and commit any changes made to a draft order (like adding items or adjusting shipping methods).

"Review the draft order edit we just created. If the total is correct, confirm the edit to apply the line items to the draft order."

Update Inventory Levels (medusa_inventory_items_batch_location_levels)

This tool handles the complex decoupling of physical stock locations from abstract inventory items. Claude can use this to rebalance stock or deduct damaged goods across multiple warehouses.

"Warehouse A reported 5 units of inventory item ID 987 were damaged. Reduce the inventory level at Location ID 555 by 5 units."

Start Return Receival (medusa_returns_begin_receive)

Automates the intake process for RMAs. Claude can initiate the receival process so warehouse staff can log damaged vs restocked items.

"Customer 404 returned their order. Start the return receival process for Return ID 999 so the warehouse team can begin logging the inbound items."

Create a Promotion (create_a_medusa_campaign)

Allows marketing teams to deploy complex rules-based campaigns. Claude can assemble the promotion logic, target specific customer groups, and deploy the campaign.

"Create a new promotional campaign for Black Friday. Set a 20 percent discount on all items in the 'Electronics' collection, valid from November 25th to November 30th."

For the complete schema definitions and the full list of available Medusa tools, view the Truto Medusa Integration page.

Workflows in Action

Providing Claude with isolated tools is useful, but the real power of an MCP server lies in the LLM's ability to chain these tools together to execute complex, multi-stage business processes.

Scenario 1: B2B Wholesale Order Generation

B2B orders rarely go through a standard checkout flow. They often require manual intervention, custom pricing, and multi-line item generation based on email requests. Claude can parse an email from a buyer and orchestrate the entire Draft Order lifecycle in Medusa.

"A distributor just emailed asking for 100 units of the 'Ergo Office Chair' and 50 units of 'Standing Desk V2'. They are an existing customer under the email corp@example.com. Please build a draft order for this request, add the items, and finalize the draft edit so it's ready for the sales team to review."

Tool Execution Sequence:

1. list_all_medusa_customers - Claude searches for corp@example.com to retrieve the Customer ID.
2. list_all_medusa_products - Claude searches the catalog to find the exact Variant IDs for the requested chairs and desks.
3. create_a_medusa_draft_order - Claude initializes a new draft order tied to the retrieved Customer ID.
4. medusa_draft_orders_add_edit_items - Claude calls this tool twice (or batches it) to append the ITEM_ADD actions for both variants and quantities to the draft order edit.
5. medusa_draft_orders_confirm_edit - Claude finalizes the edit, committing the items to the draft order.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Medusa as Medusa API

    Claude->>Truto: call list_all_medusa_customers(query)
    Truto->>Medusa: GET /admin/customers
    Medusa-->>Claude: Returns Customer ID
    
    Claude->>Truto: call create_a_medusa_draft_order(customer_id)
    Truto->>Medusa: POST /admin/draft-orders
    Medusa-->>Claude: Returns Draft Order & Edit ID
    
    Claude->>Truto: call medusa_draft_orders_add_edit_items(edit_id, items)
    Truto->>Medusa: POST /admin/draft-orders/edits/{id}/items
    Medusa-->>Claude: Items Added
    
    Claude->>Truto: call medusa_draft_orders_confirm_edit(edit_id)
    Truto->>Medusa: POST /admin/draft-orders/edits/{id}/confirm
    Medusa-->>Claude: Draft Order Finalized

Scenario 2: Processing a Return and Restocking

Returns require updating the order status, logging the inbound shipment, and deciding whether items go back into sellable inventory or are written off as damaged.

"We just received the return shipment for Return ID RET-123. The customer returned 2 shirts. One is in perfect condition and should be restocked. The other is torn and must be dismissed as damaged. Process this receival in Medusa."

Tool Execution Sequence:

1. medusa_returns_begin_receive - Claude initiates the receival process for the specified Return ID.
2. medusa_returns_add_receive_items - Claude logs the perfect-condition shirt, appending a RECEIVE_RETURN_ITEM action so the stock is automatically adjusted back into inventory upon confirmation.
3. medusa_returns_add_dismiss_items - Claude logs the torn shirt, appending a RECEIVE_DAMAGED_RETURN_ITEM action so the financial refund is processed but the item is written off and not restocked.
4. medusa_returns_confirm_receive - Claude confirms the receival process, executing the state changes across the order and inventory ledgers.

Handling Medusa's Rate Limits

When deploying AI agents that run loop-heavy operations (like auditing hundreds of line items), you will inevitably encounter Medusa's API rate limits.

It is critical to understand that Truto does not absorb, retry, or throttle rate limit errors on your behalf. If Claude attempts to execute 100 tool calls in three seconds and the upstream Medusa API rejects the burst with an HTTP 429 status code, Truto passes that error directly back to the LLM.

Truto normalizes the upstream rate limit data into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This explicitly shifts the responsibility of backoff and retry logic to the caller. Your agent orchestration framework (or Claude's internal tool-retry behavior) must read these headers and pause execution appropriately.

Security and Access Control

Giving an AI model unrestricted write access to your financial and commerce infrastructure is dangerous. Truto provides several mechanisms at the MCP token level to strictly bound what Claude can do:

• Method Filtering: You can restrict a token to "methods": ["read"]. This allows Claude to query orders and inventory but physically prevents it from calling any create, update, or delete tools, enforcing a strict read-only boundary.
• Tag Filtering: By configuring "tags": ["products", "inventory"], you can generate an MCP server that only exposes catalog management tools, hiding all sensitive financial, customer, and order-processing operations from the LLM.
• Enforced Expirations: Using the expires_at parameter, you can provision just-in-time access for contractors or temporary AI workflows. Once the timestamp passes, Truto automatically schedules a cleanup alarm and destroys the token.
• Secondary Authentication: By setting require_api_token_auth: true, possession of the MCP URL alone is no longer enough to execute a tool. The client must also pass a valid Truto API token in the Authorization header, preventing unauthorized usage if the URL leaks.

The Strategic Advantage of Managed MCPs

Building an AI agent that can reason about B2B commerce requires high-fidelity, real-time access to the underlying platform. But Medusa's heavily decoupled architecture - where inventory, pricing, and products live in completely separate domains - makes hand-coding a custom integration layer an exercise in frustration. Every time you add a tool, you are writing custom JSON-RPC wrappers, managing HTTP clients, and updating complex TypeScript schemas.

Truto fundamentally changes this calculus. By dynamically generating tools directly from Medusa's documentation and resource metadata, Truto ensures that your MCP server always reflects the actual shape of the API. You get secure, tokenized, read-and-write AI access to your commerce engine in minutes, without writing a single line of integration code.