---
title: "Connect Medusa to ChatGPT: Sync orders, inventory, and customers"
slug: connect-medusa-to-chatgpt-sync-orders-inventory-and-customers
date: 2026-10-19
author: Roopendra Talekar
categories: ["AI & Agents"]
excerpt: "Learn how to connect Medusa to ChatGPT using Truto's auto-generated MCP servers. A technical guide to automating e-commerce orders, inventory, and customers."
tldr: "Connect Medusa to ChatGPT in minutes using Truto's auto-generated MCP servers. This guide covers how to expose Medusa's API to AI agents, handle e-commerce workflows, and enforce security controls."
canonical: https://truto.one/blog/connect-medusa-to-chatgpt-sync-orders-inventory-and-customers/
---

# 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](https://truto.one/blog/what-is-mcp-and-mcp-servers-and-how-do-they-work/). If your team uses Claude, check out our guide on [connecting Medusa to Claude](https://truto.one/blog/connect-medusa-to-claude-manage-catalogs-and-complex-order-flows/) or explore our broader architectural overview on [connecting Medusa to AI Agents](https://truto.one/blog/connect-medusa-to-ai-agents-automate-promotions-and-shipping/).

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](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) 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.

> Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the Medusa API

A custom MCP server is essentially a self-hosted API translation layer. While the [open MCP standard](https://truto.one/blog/what-is-mcp-model-context-protocol-the-2026-guide-for-saas-pms/) 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](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) 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](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) into your own SaaS product.

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

```bash
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:

```json
{
  "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:

```json
{
  "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](https://truto.one/integrations/detail/medusa).

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

```mermaid
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.

> Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
>
> [Talk to us](https://truto.one/book-a-demo/)