Connect Ecwid to Claude: Manage Orders, Customers, and Invoices

If you are scaling an e-commerce operation on Ecwid, managing orders, updating stock levels, and handling customer support inquiries manually quickly becomes a bottleneck. To automate these workflows, you need a Model Context Protocol (MCP) server that connects your Ecwid store data directly to a Large Language Model (LLM). You can either build and maintain this translation layer yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL—similar to the workflow for connecting BigCommerce to Claude.

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

Giving an AI agent read and write access to a live e-commerce database is an engineering challenge. You have to map highly nested catalog schemas to MCP tool definitions, inject store IDs into every request context, and handle Ecwid's specific rate limiting rules. Every time Ecwid updates an endpoint or deprecates a field, 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 Ecwid, connect it natively to Claude Desktop, and execute complex e-commerce workflows using natural language.

The Engineering Reality of the Ecwid API

A custom MCP server is a self-hosted API layer that translates an LLM's JSON-RPC tool calls into vendor-specific HTTP requests. While the open MCP standard provides a predictable way for Claude to discover tools, the reality of implementing it against Ecwid's API introduces several specific integration hurdles.

If you decide to build a custom MCP server for Ecwid, you own the entire integration lifecycle. Here are the specific challenges you will face:

Store ID Context Injection Unlike many SaaS APIs where an OAuth token implicitly identifies the tenant account, Ecwid requires the store_id to be explicitly passed in the path of almost every API request (e.g., /api/v3/{store_id}/orders). When exposing tools to an LLM, asking the model to magically know and pass the correct Store ID is a recipe for hallucinations. Your MCP server must securely inject this context on the backend before the request hits Ecwid, while abstracting it away from the LLM's required schema.

Complex Product vs. Variation Schemas Ecwid's catalog data model strictly separates base products from product variations (combinations). If an LLM needs to adjust the stock of a "Large Red T-Shirt", it cannot simply update the base product. It must query the product, list its variations, identify the correct variation ID, and execute a stock adjustment against the variation endpoint. The schemas for base products and variations overlap heavily but are not identical. Hand-coding these exact JSON schemas into MCP tool definitions is tedious and error-prone.

Strict API Rate Limits and Backoff Ecwid enforces varying rate limits depending on the store's pricing tier (ranging from a few hundred to thousands of requests per minute). If your AI agent gets stuck in a loop scraping hundreds of product reviews or batch-updating orders, Ecwid will return an HTTP 429 Too Many Requests error.

It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Ecwid 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 agent framework) is strictly responsible for interpreting these headers and executing the appropriate retry and backoff logic.

Instead of building this infrastructure from scratch, you can use Truto to dynamically generate Ecwid MCP tools directly from documentation records and integration schemas, completely eliminating the boilerplate.

How to Generate an Ecwid MCP Server with Truto

Truto creates MCP tools dynamically based on an integration's API resources and documentation. Rather than hardcoding a list of endpoints, Truto inspects the authenticated Ecwid account, reads the available documented methods, and serves them as fully qualified JSON-RPC 2.0 tools.

You can generate an MCP server for Ecwid in two ways: via the Truto UI or programmatically via the API.

Method 1: Creating the Server via the Truto UI

For internal tooling, IT admins, and non-programmatic setups, the Truto dashboard provides a one-click server generation flow.

1. Navigate to the Integrated Accounts page in your Truto environment and select your connected Ecwid instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define your server configuration. You can assign a human-readable name, select method filters (e.g., only allow read operations), and set an optional expiration date (TTL).
5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

This URL contains a securely hashed cryptographic token that embeds the integration context, the store ID, and the access filters. No other authentication is required by default.

Method 2: Creating the Server via the API

For developers building programmatic agents, you can generate an MCP server dynamically by sending a POST request to the Truto API. This is ideal for provisioning temporary, scoped toolsets for background worker agents.

Endpoint: POST /integrated-account/:id/mcp

// Request
await fetch('https://api.truto.one/integrated-account/ab12-cd34-ef56/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Ecwid Fulfillment Agent",
    config: {
      methods: ["read", "update"],
      tags: ["orders", "inventory"]
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});

Response:

{
  "id": "mcp-789-xyz",
  "name": "Ecwid Fulfillment Agent",
  "config": {
    "methods": ["read", "update"],
    "tags": ["orders", "inventory"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Truto validates that the integration has tools available (AI-readiness check). If successful, it securely provisions the endpoint and returns the URL. The underlying token is never stored in plaintext.

Connecting the MCP Server to Claude

Once you have the generated Truto MCP URL, you need to configure your client to connect to it. Since Truto uses Server-Sent Events (SSE) for remote MCP transport, you can connect directly without hosting a local proxy.

Method 1: Via the Claude Desktop UI

If you are using the official Claude Desktop application or a supported enterprise UI (like ChatGPT Developer Mode):

1. Open Claude Desktop and navigate to Settings -> Integrations.
2. Click Add MCP Server (or Custom Connector).
3. Provide a name (e.g., "Ecwid Store Admin").
4. Paste the Truto MCP URL directly into the URL field.
5. Click Add.

Claude will immediately initiate the handshake, request the tools/list, and populate its context window with the available Ecwid API operations.

Method 2: Via the Manual Configuration File

For advanced users, CI/CD pipelines, or programmatic Claude instances, you can configure the connection via the standard claude_desktop_config.json file.

Since Truto exposes an SSE endpoint, you use the standard @modelcontextprotocol/server-sse npx wrapper to route the local STDIO protocol over HTTP to Truto.

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

Restart Claude Desktop. The application will execute the npx command, establish the SSE connection, and dynamically load the Ecwid schema definitions.

Hero Tools for Ecwid AI Agents

Truto exposes the entirety of Ecwid's documented REST API as MCP tools. When the LLM requests tools/list, Truto translates the integration's schemas into clean, JSON Schema representations.

Here are 6 high-leverage hero tools your AI agents can use to automate e-commerce tasks.

1. get_single_ecwid_order_by_id

Retrieves the full order object from Ecwid, including line items, shipping details, customer contact info, and current fulfillment status. This is the cornerstone tool for automated customer support.

"A customer just emailed asking for an update on order #84920. Please fetch the order details and tell me if it has shipped yet."

2. update_a_ecwid_order_by_id

Updates an existing Ecwid order. You can use this to append internal notes, adjust customer information, or programmatically trigger fulfillment updates.

"The customer for order #84920 called to say their apartment number is 4B. Update the order shipping details to reflect this change."

3. list_all_ecwid_product

Searches and lists products in the store catalog. It supports robust filtering, allowing Claude to find items by SKU, name, or category, and returns stock availability and pricing.

"Find all products containing 'Summer Cap' in the catalog and list their current stock levels and prices."

4. ecwid_product_adjust_stock

Directly adjusts the stock quantity of a specific product (or product variation) using a delta value, rather than requiring the agent to calculate and set an absolute stock number.

"We just found 12 extra units of the 'Summer Cap' (ID: 99482) in the warehouse. Please increase its stock count by 12."

5. create_a_ecwid_discount_coupon

Generates a new discount code on the fly. This is exceptionally powerful for AI support agents aiming to handle customer appeasements without human intervention, much like connecting Stripe to Claude allows for automated financial reconciliation.

"Create a single-use discount coupon for 15% off that expires in 30 days. Give me the code so I can email it to a frustrated customer."

6. list_all_ecwid_abandoned_cart

Fetches carts that customers populated but never checked out. An agent can analyze this list to initiate hyper-personalized recovery sequences.

"Pull the list of abandoned carts from the last 24 hours. Identify any carts over $150 and draft personalized follow-up emails offering free shipping."

To view the complete inventory of available Ecwid tools, request schemas, and pagination logic, visit the Ecwid integration page.

Workflows in Action

MCP servers transform LLMs from static text generators into autonomous agents capable of executing multi-step business logic. Here is how Claude utilizes the Ecwid MCP server to solve real e-commerce problems.

Scenario 1: Autonomous Customer Support Triage

Handling "where is my order" (WISMO) requests is the most time-consuming task for any e-commerce support team. With MCP, Claude can handle the entire investigation and appeasement lifecycle, providing a level of automation similar to connecting Zendesk to Claude for managing support documentation.

"A customer named Sarah Jenkins just opened a ticket complaining that her recent order is extremely delayed. Find her order, check the status, add an internal note that the customer is upset, and generate a 20% off apology coupon for her next purchase."

Agent Execution Flow:

1. Call list_all_ecwid_order: Claude passes email: sarah.jenkins@example.com as a query parameter to locate her most recent order. If her contact history was stored elsewhere, you might also be connecting HubSpot to Claude to pull full CRM context.
2. Call get_single_ecwid_order_by_id: Claude extracts the id from the list response to pull the full payload, noting that fulfillmentStatus is PROCESSING instead of SHIPPED.
3. Call update_a_ecwid_order_by_id: Claude updates the staffNote field on the order to indicate the customer escalation.
4. Call create_a_ecwid_discount_coupon: Claude creates a discount coupon with discountType: PERCENT, discount: 20, and usesLimit: 1.

Result: The user receives a comprehensive summary of the delay, confirmation that the order note was logged in Ecwid, and a newly generated, ready-to-send coupon code.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Ecwid as Ecwid API

    User->>Claude: "Check Sarah's delayed order and make a coupon"
    Claude->>Truto: call list_all_ecwid_order (email)
    Truto->>Ecwid: GET /orders?email=...
    Ecwid-->>Truto: Return order ID 1045
    Truto-->>Claude: JSON order data
    Claude->>Truto: call update_a_ecwid_order_by_id (note)
    Truto->>Ecwid: PUT /orders/1045
    Ecwid-->>Truto: 200 OK
    Truto-->>Claude: Update success
    Claude->>Truto: call create_a_ecwid_discount_coupon
    Truto->>Ecwid: POST /discount_coupons
    Ecwid-->>Truto: Coupon code "SORRY20"
    Truto-->>Claude: Coupon created
    Claude-->>User: "Order updated. Coupon SORRY20 generated."

Scenario 2: Flash Sale Inventory Sweeps

During high-volume sales periods, catalog management requires constant monitoring. You can ask Claude to act as an automated merchandising assistant.

"Audit the 'Winter Clearance' category. Find any products with fewer than 5 items in stock, append ' [LOW STOCK]' to their product names, and reduce their price by an additional $5 to clear them out."

Agent Execution Flow:

1. Call list_all_ecwid_category: Claude locates the "Winter Clearance" category ID.
2. Call list_all_ecwid_product: Claude filters for products belonging to that specific category.
3. Data Analysis Loop: Claude iterates through the JSON response, identifying items where inStock < 5.
4. Call update_a_ecwid_product_by_id: For each low-stock item, Claude sends a PUT request, modifying the name and subtracting $5 from the price field.

Result: Claude systematically audits the catalog and executes pricing and title updates, providing a final report of exactly which SKUs were modified.

Security and Access Control

Connecting a powerful LLM to a live e-commerce store requires strict governance. Truto's MCP servers provide deep, token-level access controls to ensure your agents operate safely.

• Method Filtering: Limit your MCP server to specific operation types. Setting methods: ["read"] prevents the LLM from executing any create, update, or delete actions, providing a safe, read-only analytical agent.
• Tag Filtering: Group tools by functional domains. Setting tags: ["orders", "customers"] restricts the server from accessing sensitive configurations like store_profile or staff_account.
• Require API Token Auth: By default, possessing the MCP server URL grants access. By setting require_api_token_auth: true, you force the client to also provide a valid Truto API session token, ensuring only authenticated human team members can invoke tools.
• Expiration (TTL): Create self-destructing access by passing an expires_at timestamp. Once expired, Truto automatically evicts the token from edge storage and destroys the server access.

Connect Ecwid to Claude Today

Building a custom integration layer for Ecwid requires mastering complex catalog structures, handling rate-limit backoffs, and writing exhaustive JSON schemas for the MCP protocol. Truto bypasses this boilerplate entirely. By dynamically generating tools from documented endpoints, normalizing the authentication lifecycle, and providing fine-grained access controls, Truto lets your engineering team focus on building better AI workflows instead of wrestling with API maintenance.