Connect EasyEcom to Claude: Manage Logistics, Shipments & Returns

If you need to connect EasyEcom to Claude to automate e-commerce operations, manage multi-channel logistics, orchestrate order fulfillment, or process pending returns, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM tool calls and EasyEcom's 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 EasyEcom to ChatGPT or explore our broader architectural overview on connecting EasyEcom to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling operational system like EasyEcom is an engineering challenge. You have to handle JWT token lifecycles, map massive e-commerce JSON schemas to MCP tool definitions, and deal with strict API rate limits. Every time EasyEcom updates an endpoint or alters a fulfillment payload, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for EasyEcom, connect it natively to Claude, and execute complex logistics and supply chain workflows using natural language.

The Engineering Reality of the EasyEcom 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 specialized B2B APIs is painful. EasyEcom is built to manage massive, multi-channel retail operations, B2B wholesale pipelines, and complex warehouse routing. Its API reflects that scale and complexity.

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

Asynchronous Reporting and Polling Logic EasyEcom does not serve massive historical datasets synchronously. If an LLM needs to analyze inventory aging or full warehouse stock, it cannot just call a simple GET. It must first initiate a report job (create_a_easy_ecom_report), capture a specific reportId, and then poll a secondary endpoint (list_all_easy_ecom_reports) until the status resolves to Finished. Finally, it must download the file from a signed URL. A naive MCP server will time out or hallucinate during this multi-step async flow. Your MCP tools must be carefully described to instruct the LLM on exactly how to navigate this polling loop.

Polymorphic Order Creation EasyEcom utilizes a single endpoint to handle entirely different business constructs. The endpoint to create orders accepts Business-to-Consumer (B2C), Business-to-Business (B2B), and Stock Transfer Notes (STN) based on a specific orderType flag. The payload requirements shift dramatically depending on this flag - B2B orders require distinct tax identification arrays, while B2C orders demand marketplace identifiers. An LLM needs heavily annotated JSON schemas in the MCP tool definition to know which fields are strictly required for which orderType.

Token Expirations and Location Keys EasyEcom relies on short-lived JWT authentication that must be refreshed using an email, password, and a specific location_key. Building a custom MCP server means you have to write custom chron jobs to fetch and rotate these JWTs every few days across every tenant you support, injecting them seamlessly into the LLM's outgoing API requests so the context window isn't polluted with auth tokens.

Generating a Managed MCP Server for EasyEcom

Truto abstracts away the authentication, token rotation, and schema generation. When you connect an EasyEcom account to Truto, it dynamically generates MCP tools based on the integration's documented API resources.

You can generate the MCP server URL using either the Truto UI or the API.

Method 1: Via the Truto UI

This is the fastest approach for internal tooling and local testing with Claude Desktop.

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected EasyEcom instance.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags like inventory).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For production use cases - like programmatically provisioning isolated MCP servers for specific tenants or automated workflows - use the Truto API.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/<easyecom_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EasyEcom Logistics AI Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API provisions the secure server, registers the EasyEcom schema tools, and returns the endpoint payload:

{
  "id": "mcp_8f7e6d5c",
  "name": "EasyEcom Logistics AI Agent",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

This single URL is fully self-contained. It cryptographically maps to the specific EasyEcom tenant and handles all underlying JWT auth.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude is straightforward.

Method A: Via the Claude UI (Web/Desktop)

If your organization uses Claude Enterprise or Claude for Teams with custom connectors enabled:

1. Open Claude and go to Settings -> Integrations.
2. Click Add MCP Server (or Add Custom Connector).
3. Paste the Truto MCP URL.
4. Click Add.

Claude will immediately ping the server, complete the JSON-RPC 2.0 handshake, and load the EasyEcom tool definitions into its context.

Method B: Via the claude_desktop_config.json

For local development or specialized desktop deployments, you can configure Claude Desktop to connect via Server-Sent Events (SSE).

Locate your claude_desktop_config.json file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following:

{
  "mcpServers": {
    "easyecom_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The agent now has direct access to the EasyEcom APIs.

Hero Tools for EasyEcom

Truto automatically maps EasyEcom's endpoints into descriptive, snake_case tools. Here are 6 high-leverage hero tools that unlock immediate value for e-commerce operators.

create_a_easy_ecom_business_order

This polymorphic tool allows Claude to inject orders directly into the warehouse pipeline. Because it relies on the orderType parameter, Claude can create B2C web orders, B2B wholesale orders, or internal Stock Transfer Notes (STNs).

Usage Note: Ensure Claude provides the required fields: orderNumber, orderDate, sku, Quantity, and Price. For marketplaces, it must supply the marketplace_id.

"A wholesale customer just called in a manual order. Create a new B2B order in EasyEcom for 50 units of SKU 'WIDGET-XL' at $12.50 each. Generate a random order number starting with 'MAN-'."

list_all_easy_ecom_orders

Retrieves a paginated list of all order types. Crucial for customer support inquiries or auditing daily fulfillment volumes.

Usage Note: Truto injects limit and next_cursor schema definitions here. Tell Claude to filter by status or date range to keep the response concise.

"List all EasyEcom orders from the last 24 hours that are currently marked as 'Pending Fulfillment'. Summarize the total unfulfilled quantity."

create_a_easy_ecom_batch_inventory_update

An asynchronous API used to overwrite or update inventory counts in bulk. Vital for reconciling cycle counts or adjusting stock after a warehouse audit.

Usage Note: This tool requires sku and quantity. If tracking expiration, batchCode must be provided.

"We just finished a cycle count on aisle 4. Update the EasyEcom inventory to reflect 120 units for SKU 'CASE-1A' and 45 units for SKU 'CASE-2B'."

create_a_easy_ecom_pending_return

Marks a specific order as a pending return (RMA) in the system, preparing the warehouse to receive inbound goods.

Usage Note: Claude needs the original reference_code, the parent_sku, the return_reason, and the return_quantity.

"Order #ORD-9932 is being returned by the customer because it arrived damaged. Mark a pending return for 1 unit of SKU 'COFFEE-MUG-BLUE' and log the reason as 'damaged in transit'."

list_all_easy_ecom_tracking_details

Fetches current courier tracking status and historical tracking events for a specific Air Waybill (AWB) or reference code.

Usage Note: Required input is either reference_code or awb_number.

"Get the tracking details for AWB number '1Z9999999999999999'. Where is the package currently located, and what is the estimated delivery date?"

create_a_easy_ecom_report

Initiates the asynchronous reporting engine. Use this to generate deep analytical exports like the FULL_INVENTORY_REPORT or INVENTORY_AGING_REPORT.

Usage Note: Claude must supply the reportType, dateType, startDate, and endDate. It will receive a reportId in response, which it must use to poll list_all_easy_ecom_reports.

"Generate an INVENTORY_AGING_REPORT in EasyEcom for the current month. Let me know when the report ID is generated, then check its status."

For the complete inventory of available EasyEcom operations and detailed JSON Schema payloads, visit the EasyEcom integration page.

Workflows in Action

Here is how Claude utilizes these tools sequentially to solve complex logistics problems.

Workflow 1: End-to-End Return Processing

When a customer requests a return via email or chat, the agent needs to verify the order, initiate the return, and check tracking status.

"A customer wants to return order #10045 because they ordered the wrong size. Set up the pending return for SKU 'SHIRT-M-RED', check the existing tracking history to confirm it was actually delivered, and summarize the next steps for the customer."

1. Claude calls list_all_easy_ecom_order_details with reference_code: "10045" to verify the SKU exists in the order.
2. Claude calls list_all_easy_ecom_tracking_details to verify the outbound shipment status is Delivered.
3. Claude calls create_a_easy_ecom_pending_return passing the reference code, SKU, quantity of 1, and reason "wrong size".

sequenceDiagram
    participant User as User Prompt
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant EasyEcom as EasyEcom API

    User->>Claude: Process return for order #10045...
    Claude->>MCP: Call list_all_easy_ecom_order_details
    MCP->>EasyEcom: GET /orders/details?reference_code=10045
    EasyEcom-->>MCP: Return order payload
    MCP-->>Claude: JSON order data
    Claude->>MCP: Call create_a_easy_ecom_pending_return
    MCP->>EasyEcom: POST /returns/pending
    EasyEcom-->>MCP: Success (Return Initiated)
    MCP-->>Claude: Return confirmation
    Claude-->>User: Return processed. Customer next steps generated.

Workflow 2: Asynchronous Inventory Auditing

When a warehouse manager needs a holistic view of dead stock, standard API listing endpoints are too slow. The agent must navigate the reporting queue.

"I need to audit our dead stock. Generate an inventory aging report for the last 90 days. Check if it's finished, and if so, give me the download link."

1. Claude calls create_a_easy_ecom_report with reportType: "INVENTORY_AGING_REPORT" and the 90-day date parameters.
2. EasyEcom returns a reportId (e.g., req_9942).
3. Claude calls list_all_easy_ecom_reports to check the queue status for that token.
4. If the message reads "Finished", Claude parses the payload to extract the signed download URL and presents it to the user.

Handling Rate Limits and API Errors

Integrating LLMs with high-throughput systems like EasyEcom often leads to rate limiting, especially if the model decides to loop over hundreds of SKUs using individual update_a_easy_ecom_product_by_id calls instead of bulk endpoints.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream EasyEcom API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the MCP client (Claude).

However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your application or the LLM framework) is entirely responsible for reading these headers, pausing execution, and applying exponential backoff before retrying the tool call.

Security and Access Control

Giving an AI agent access to your logistics and order management core requires strict guardrails. Truto provides several configuration layers when creating an MCP server:

• Method Filtering (methods): Restrict the MCP server to specific operation types. Set config.methods: ["read"] to allow only get and list endpoints, preventing Claude from altering inventory or creating bogus orders.
• Tag Filtering (tags): Group tools logically. If you only want an agent handling returns, you can pass a tags array to expose only RMA and tracking related endpoints.
• API Token Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting this flag to true, the MCP server requires the client to pass a valid Truto API token in the Authorization header, enforcing a secondary identity check.
• Time-to-Live (expires_at): Ideal for temporary contractors or one-off automation scripts. Set an ISO datetime, and the MCP server will automatically self-destruct and revoke access when the time expires.

Moving Beyond Point-to-Point Integrations

Connecting Claude to EasyEcom using a custom-built MCP server means committing engineering hours to token rotation, schema validation, and endpoint maintenance. If EasyEcom deprecates a V1 fulfillment endpoint, your AI agent breaks.

By leveraging a managed integration platform, you abstract the integration layer entirely. The LLM interacts with a standardized, documentation-driven JSON-RPC interface, while the platform handles the underlying API chaos.