Connect Medusa to ChatGPT: Sync orders, inventory, and customers

If you are building autonomous e-commerce workflows, you need to give your AI agents read and write access to your store's backend. To connect Medusa to ChatGPT so your agents can draft orders, adjust inventory levels, and manage customer records, you need a Model Context Protocol (MCP) server. If your team uses Claude, check out our guide on connecting Medusa to Claude or explore our broader architectural overview on connecting Medusa to AI Agents.

Giving a Large Language Model (LLM) access to a headless commerce engine like Medusa is a significant engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server to translate LLM JSON arguments into Medusa's highly relational payload structures, or you use a managed infrastructure layer.

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

The Engineering Reality of the Medusa API

A custom MCP server is essentially a self-hosted API translation layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Medusa's highly structured commerce API comes with unique friction points.

If you decide to build a custom MCP server for Medusa, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Medusa:

The Expand and Select Paradigm

E-commerce data is heavily relational. A Medusa Order object relies on a web of relations: items, customer, shipping_address, billing_address, payments, and fulfillments. By default, Medusa APIs do not return these relational objects to keep payload sizes small. If an LLM asks "What is the shipping address for order #1234?", a standard GET /admin/orders/1234 will likely return an empty or omitted shipping address object. Your MCP server must be smart enough to inject expand=shipping_address,customer into query parameters dynamically. If you fail to map this requirement into your MCP tool descriptions, the LLM will hallucinate data because it cannot "see" the nested relationships.

Multi-Step Edit State Machines

Modifying an existing order in Medusa is not a simple PATCH request. It follows a strict state machine. You cannot directly change an order's contents. Instead, you must create an Order Edit, add or remove items within that specific edit session, request confirmation from the customer (or force confirm it as an admin), and then apply the edit. Building this sequence into an LLM workflow requires exposing multiple precise tool endpoints (begin_edit, add_edit_items, confirm_edit) and strictly prompting the agent to follow the sequence.

Inventory Location Levels

Medusa v2 handles inventory at a granular, multi-location level. An InventoryItem does not just have a "stock count." It has LocationLevels tracking stocked, reserved, and available quantities across different warehouses. If your LLM attempts to adjust inventory using a generic update_item endpoint, it will fail. You must route the LLM to the batch_location_levels endpoints, passing specific location IDs alongside the adjustments.

Factual note on rate limits

When orchestrating high-volume e-commerce tasks, you will inevitably hit API limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Medusa API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your AI agent framework or ChatGPT client) is entirely responsible for detecting these 429s and executing retry and backoff logic. Do not assume your MCP server will automatically absorb these limits.

Step 1: Create a Medusa MCP Server

Truto derives MCP tools dynamically from Medusa's resource definitions and schema documentation. A tool only appears in the MCP server if it has corresponding schema documentation, ensuring your LLMs are not exposed to undocumented or unstable endpoints.

Each MCP server is scoped to a single connected Medusa account and is secured by a cryptographic token embedded in the URL. You can generate this server via the Truto UI or programmatically via the API.

Option A: Via the Truto UI

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Medusa account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods or orders tags).
6. Copy the generated MCP server URL. Treat this URL as a secure credential.

Option B: Via the Truto API

You can dynamically generate an MCP server for your users programmatically. This is how you embed agentic capabilities into your own SaaS product.

Send a POST request to /integrated-account/:id/mcp, passing the integrated_account_id of the authenticated Medusa connection.

curl -X POST https://api.truto.one/integrated-account/<integrated_account_id>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medusa E-Commerce Agent",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["orders", "inventory", "customers"]
    }
  }'

The API responds with the tokenized URL that handles protocol routing and authentication natively:

{
  "id": "abc-123",
  "name": "Medusa E-Commerce Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["orders", "inventory", "customers"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Step 2: Connect the MCP Server to ChatGPT

Once you have your Truto MCP URL, you can plug it into your ChatGPT client. You can do this through the desktop interface or by configuring it programmatically for custom agent stacks.

Option A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle on Developer mode (MCP capabilities require this flag to be enabled).
3. Under MCP servers / Custom connectors, click to add a new server.
4. Name: Enter a descriptive name (e.g., "Medusa Store Ops").
5. Server URL: Paste the url you generated from Truto (https://api.truto.one/mcp/<token>).
6. Save your settings. ChatGPT will immediately perform the JSON-RPC handshake, discover the Medusa capabilities, and map them to its internal tool registry.

(Note: Developer Mode is available on Pro, Plus, Business, Enterprise, and Education accounts).

Option B: Via Manual SSE Configuration

If you are running headless AI agents or connecting through a custom framework, you can route MCP traffic over Server-Sent Events (SSE) using the @modelcontextprotocol/server-sse package in a standard JSON config file.

Create a config file specifying the proxy command:

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

This configuration ensures your framework communicates perfectly with the Truto JSON-RPC 2.0 endpoint.

Medusa E-Commerce Hero Tools

Truto automatically translates Medusa's E-Commerce endpoints into LLM-friendly schemas. Here are six high-leverage hero tools your agents can use immediately.

List All Orders

Tool: list_all_medusa_orders

Retrieves a list of orders. This is the starting point for support operations. Agents must use this to find order IDs before executing refunds, fulfillment checks, or edits.

"Find the most recent order for customer 'sarah@example.com'. Make sure to expand the shipping_address and items in your query so I can see what she bought."

Create a Draft Order

Tool: create_a_medusa_draft_order

Creates a draft order in the system. This tool is vital for B2B sales automation or customer support reps building carts on behalf of users. The agent must format the items and pricing correctly to successfully generate the draft.

"Draft a new B2B wholesale order for Acme Corp containing 50 units of the 'Pro Coffee Grinder' SKU. Set the shipping method to standard freight."

Batch Inventory Location Levels

Tool: medusa_inventory_items_batch_location_levels

Manages inventory levels by creating, updating, or deleting stock records at specific location IDs. Essential for warehouse operations and reconciling physical counts.

"We just received a shipment at the West Coast warehouse. Increase the stocked quantity of inventory item 'inv_12345' by 200 units at location 'loc_9876'."

Manage Promotion Rules

Tool: medusa_promotions_batch_rules

Creates, updates, or deletes the specific rule criteria applied to a promotion campaign. Allows an AI agent to dynamically adjust marketing campaigns based on stock levels or seasonality.

"Update our 'SummerSale2026' promotion rules. Add a target rule that restricts the 20% discount to products in the 'Swimwear' category only."

Execute a Workflow

Tool: medusa_workflows_executions_run

Executes a custom workflow by its ID. Medusa v2 heavily utilizes workflows for orchestrating multi-step background tasks (like product imports or complex ERP syncs). This tool allows LLMs to trigger deep backend logic.

"Trigger the 'export-inventory-items' workflow so our external 3PL can sync up with our latest stock numbers."

Confirm a Claim Request

Tool: medusa_claims_confirm_request

Finalizes an exchange or return claim, applying the changes to the associated order. This tool represents the final step in a multi-part return authorization workflow handled by an AI customer support agent.

"The customer agreed to the exchange terms for order #8821. Confirm the claim request 'claim_abc123' to apply the inbound and outbound item changes."

For the complete inventory of available Medusa endpoints, including detailed schemas for products, price lists, fulfillment sets, and multi-currency configurations, visit the Truto Medusa Integration Page.

Workflows in Action

Connecting ChatGPT to Medusa unlocks powerful automation for e-commerce operators. Because Truto flattens the input namespaces and handles schema parsing automatically, the LLM can chain together complex business logic.

Scenario 1: B2B Wholesale Order Generation

A B2B account manager needs to quickly spin up a massive wholesale order for a client via chat, rather than clicking through the Medusa Admin panel.

"Sarah from MegaMart just emailed. Build a new draft order for her account. Add 100 units of the 'Industrial Espresso Machine' and 500 units of 'Filter Packs'. Apply a 15% manual discount, attach standard B2B freight shipping, and finalize the draft so I can email her the payment link."

How the agent executes this:

1. Calls list_all_medusa_customers filtering by the query "MegaMart" to retrieve the customer ID.
2. Calls list_all_medusa_products to find the exact variant IDs for the espresso machines and filters.
3. Calls create_a_medusa_draft_order to instantiate the cart.
4. Calls medusa_draft_orders_add_edit_items to push the 100 machines and 500 filters into the draft.
5. Calls medusa_draft_orders_add_edit_shipping_method to attach the freight option.
6. Calls update_a_medusa_draft_order_by_id to apply the manual discount modifier.

Result: The agent replies with the completed Draft Order ID and a summary, ready for the account manager to generate a payment link.

Scenario 2: Automated RMA and Claim Processing

A customer service agent tasks the AI with processing a complex exchange due to a damaged item.

"Order #5512 arrived with a shattered screen. The customer wants an exchange. Create a claim for the damaged item, mark the original item to be written off, add a replacement unit to the outbound shipment, and confirm the request."

How the agent executes this:

1. Calls list_all_medusa_orders to retrieve internal IDs for Order #5512 and its specific line items.
2. Calls create_a_medusa_claim against the order to open a claim session.
3. Calls medusa_claims_add_claim_items using the WRITE_OFF_ITEM action to mark the broken screen as unrecoverable inventory.
4. Calls medusa_claims_add_outbound_items to add the replacement screen to the fulfillment queue.
5. Calls medusa_claims_confirm_request to apply the state changes permanently to the order.

Result: The agent fully processes the RMA without human intervention, logging the write-off and queuing the new shipment for the warehouse.

sequenceDiagram
  participant ChatGPT as ChatGPT (Client)
  participant MCP as Truto MCP Server
  participant Medusa as Medusa API

  ChatGPT->>MCP: Call list_all_medusa_orders<br>(query: "#5512")
  MCP->>Medusa: GET /admin/orders?q=#5512
  Medusa-->>MCP: Returns Order Payload
  MCP-->>ChatGPT: Order ID & Line Items
  
  ChatGPT->>MCP: Call create_a_medusa_claim
  MCP->>Medusa: POST /admin/orders/{id}/claims
  Medusa-->>MCP: Returns Claim ID
  MCP-->>ChatGPT: Claim initialized
  
  ChatGPT->>MCP: Call medusa_claims_add_claim_items<br>(action: "WRITE_OFF_ITEM")
  MCP->>Medusa: POST /admin/claims/{id}/items
  Medusa-->>MCP: Success
  MCP-->>ChatGPT: Item written off
  
  ChatGPT->>MCP: Call medusa_claims_confirm_request
  MCP->>Medusa: POST /admin/claims/{id}/confirm
  Medusa-->>MCP: State Applied
  MCP-->>ChatGPT: Workflow Complete

Security and Access Control

Exposing an e-commerce backend to an LLM requires strict security parameters. Truto enforces constraints at the server creation level, ensuring the URL itself acts as a bounded capability token:

• Method filtering: You can restrict a Medusa MCP server to strictly read-only operations using methods: ["read"]. This allows an agent to query inventory or order status without having the ability to alter store data.
• Tag filtering: Isolate AI operations by domain. For a marketing agent, apply tags: ["promotions", "campaigns"] to strip out dangerous endpoints like order modification or payment capture.
• Double Authentication: By setting require_api_token_auth: true, possession of the MCP URL is no longer enough. The ChatGPT client must also pass a valid Truto API token in the Authorization header to connect, preventing unauthorized access if the URL leaks.
• Auto-expiration: Generate ephemeral environments for external contractors by setting an expires_at timestamp. Once the clock runs out, Truto's Durable Object alarms trigger a hard deletion of the token from the KV store and database.

Connect Your Agent Frameworks Today

Building a custom integration layer for Medusa requires handling dense relational data models, navigating complex e-commerce state machines, and manually building JSON-RPC routing for hundreds of endpoints. Truto handles this instantly.

By generating a Truto MCP server, you give ChatGPT safe, documented, and strictly controlled access to your Medusa backend in seconds, freeing your engineers to focus on workflow logic instead of API boilerplate.