--- title: "Connect Lightspeed to Claude: Sync Customer Groups and Inventory" slug: connect-lightspeed-to-claude-sync-customer-groups-and-inventory date: 2026-09-28 author: Nachi Raman categories: ["AI & Agents"] excerpt: "Learn how to connect Lightspeed to Claude using a managed MCP server. This step-by-step guide covers handling complex retail APIs, inventory tools, and AI workflows." tldr: "Connect Lightspeed to Claude via Truto's managed MCP server to automate retail operations. Learn to handle Lightspeed's strict APIs, deploy inventory tools, and execute natural language workflows." canonical: https://truto.one/blog/connect-lightspeed-to-claude-sync-customer-groups-and-inventory/ --- # Connect Lightspeed to Claude: Sync Customer Groups and Inventory If your team needs to connect Lightspeed to Claude to automate inventory management, sync customer loyalty groups, or track complex supplier consignments, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's tool calls and Lightspeed Retail (X-Series) REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like [Truto](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on [/connect-lightspeed-to-chatgpt-manage-retail-stock-and-sales/](https://truto.one/connect-lightspeed-to-chatgpt-manage-retail-stock-and-sales/) or explore our broader architectural overview on [/connect-lightspeed-to-ai-agents-automate-supply-chain-and-loyalty/](https://truto.one/connect-lightspeed-to-ai-agents-automate-supply-chain-and-loyalty/). Giving a Large Language Model (LLM) read and write access to a specialized retail management ecosystem like Lightspeed is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map Lightspeed's highly specific version-based pagination to MCP tool definitions, and deal with strict consignment state machines. Every time Lightspeed updates an endpoint, 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 Lightspeed, connect it natively to Claude Desktop or enterprise AI agents, and execute complex retail workflows using natural language. > Want to give your AI agents secure, authenticated access to Lightspeed and 100+ other SaaS APIs? Let's talk about managed MCP architecture. > > [Talk to us](https://truto.one/book-a-demo/) ## The Engineering Reality of the Lightspeed 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 retail APIs is painful. Lightspeed Retail (X-Series) is built to manage massive catalogs, multi-outlet inventory, and complex supplier relationships. Its API reflects that complexity. If you decide to [build a custom Lightspeed MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), here are the specific integration challenges you will face: **Version-Based Syncing Over Traditional Pagination** Unlike APIs that use standard `page=2` or offset-based pagination, Lightspeed relies heavily on a `version` attribute. Every record (customer, product, sale) has a version number that acts as a global sequential counter. To paginate through massive catalogs or sync updates, you must query using `after` and `before` version bounds. If your MCP tools expose raw pagination endpoints to an LLM without strict cursor management, the LLM will easily hallucinate `page` parameters or fail to fetch subsequent records. A managed MCP server wraps these endpoints, injecting `limit` and `next_cursor` fields into the schema so the model can paginate reliably without understanding the underlying version architecture. **The Strict Consignment State Machine** Lightspeed enforces rigid business logic around consignments (purchase orders, inventory transfers, stocktakes, and returns). A consignment has a `type` (e.g., SUPPLIER, OUTLET) and a `status` (e.g., OPEN, DISPATCHED, RECEIVED, CANCELLED). You cannot simply update a consignment to change its type once created, nor can you add products to a SUPPLIER order that is already marked RECEIVED or CANCELLED. If an LLM attempts an invalid state transition, the API will throw domain-specific errors. The integration layer must expose these rules clearly via OpenAPI schemas so the model understands what operations are permissible based on the consignment's current status. **Product Variant Hierarchies** Managing products in Lightspeed means dealing with families of variants. Products have `has_variants` and `variant_parent_id` flags. Deleting a variant via the API only removes that specific SKU from its family - it does not delete the parent product if other siblings exist. Conversely, creating products requires understanding whether you are creating a standalone item or appending a variant to an existing matrix. An LLM needs explicit schema descriptions outlining when and how to pass `variant_parent_id` to prevent corrupting the catalog structure. ## Generating the Managed Lightspeed MCP Server Instead of building an MCP server from scratch to handle these quirks, you can use Truto to dynamically generate one. Truto derives tool definitions directly from Lightspeed's resource schemas and API documentation. Before you create the server, you must connect a Lightspeed account. Truto handles the OAuth 2.0 handshake, securely stores the token, and automatically refreshes it in the background. Once the account is connected, you can generate the MCP server in two ways. ### Method 1: Via the Truto UI For teams who prefer a visual interface: 1. Navigate to the **Integrated Accounts** page in the Truto dashboard. 2. Select your connected Lightspeed account. 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/abc123xyz...`). ### Method 2: Via the Truto API For platform engineering teams automating agent provisioning, you can generate the server programmatically. Make an authenticated `POST` request to the Truto API: ```bash curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \ -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Lightspeed Inventory Agent", "config": { "methods": ["read", "write"], "tags": ["inventory", "customers"] } }' ``` The response contains the secure URL you will provide to Claude: ```json { "id": "mcp_abc123", "name": "Lightspeed Inventory Agent", "url": "https://api.truto.one/mcp/abc123xyz789...", "config": { "methods": ["read", "write"], "tags": ["inventory", "customers"] } } ``` ### A Crucial Note on API Rate Limits When exposing Lightspeed to an LLM, the model may aggressively iterate through paginated endpoints, hitting Lightspeed's rate limits. **Truto does not retry, throttle, or apply backoff on rate limit errors.** When the upstream Lightspeed API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized HTTP headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller (your AI agent framework or Claude client) is strictly responsible for inspecting these headers and implementing its own retry or backoff logic. Do not assume the integration layer will magically absorb LLM-induced API spam. ## Connecting the Lightspeed MCP Server to Claude Once you have your Truto MCP URL, you can connect it to Claude. The server uses JSON-RPC 2.0 over HTTP, allowing Claude to discover and execute tools securely. ### Method A: Via the Claude UI If you are using Claude Desktop or an enterprise workspace that supports visual connector management: 1. Open **Settings** in Claude. 2. Navigate to **Integrations** or **Connectors**. 3. Click **Add MCP Server** or **Add custom connector**. 4. Name the connection (e.g., "Lightspeed Retail"). 5. Paste the Truto MCP URL. 6. Click **Add**. Claude will immediately handshake with the server and discover the available Lightspeed tools. *(Note: If you use ChatGPT, the flow is similar: Settings -> Apps -> Advanced settings -> Developer mode -> Add Custom Connector).* ### Method B: Via Manual Config File (Claude Desktop) For local development or headless deployments, you can configure Claude Desktop using the `claude_desktop_config.json` file. Because Truto's MCP servers communicate via HTTP Server-Sent Events (SSE), you will use the official `@modelcontextprotocol/server-sse` transport. Add the following to your configuration file: ```json { "mcpServers": { "lightspeed": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-sse", "https://api.truto.one/mcp/abc123xyz789..." ] } } } ``` Restart Claude Desktop. When you open a new chat, the Lightspeed tools will be available. ## Hero Tools for Lightspeed Operations Lightspeed has dozens of endpoints, but exposing everything to an LLM can overwhelm its context window. A highly effective Lightspeed AI agent relies on a focused set of "hero tools." Here are the highest-leverage tools available in the Truto Lightspeed integration. ### List All Lightspeed Products The `list_all_lightspeed_products` tool allows Claude to pull paginated product catalogs. It returns detailed records including `id`, `name`, `sku`, `retail_price`, `supply_price`, and `tax_id`. This is essential for inventory checks and auditing catalog data. > "Claude, pull the first page of our Lightspeed products. I need to audit the retail prices and SKUs for our latest shipment. If there is a next_cursor, let me know so we can fetch the rest." ### Get Single Lightspeed Product by ID The `get_single_lightspeed_product_by_id` tool fetches deep details for a specific item. Crucially, this exposes variant data (`has_variants`, `variant_parent_id`), allowing the LLM to understand if an item is a standalone product or part of a larger size/color matrix. > "Fetch the details for the product ID 'prod_889900'. I need to know its supply price, brand ID, and whether it has child variants." ### List All Lightspeed Customers The `list_all_lightspeed_customers` tool retrieves customer records, including names, contact details, `customer_group_id`, and `loyalty_balance`. The tool handles version-range and deleted-record filters, making it easy to sync audiences. > "Retrieve a list of all our Lightspeed customers. Extract their email addresses and current loyalty balances so we can build a high-value customer segment." ### Update a Lightspeed Customer by ID Using `update_a_lightspeed_customer_by_id`, the agent can modify existing shopper profiles. This is particularly useful for assigning customers to new VIP tiers by updating their `customer_group_id` based on recent purchase behavior. > "Update the customer record for ID 'cust_554433'. Change their customer_group_id to 'grp_vip' and update their phone number to 555-0199." ### Create a Lightspeed Consignment The `create_a_lightspeed_consignment` tool allows the agent to generate new purchase orders, stocktakes, or supplier returns. The LLM must supply a `name`, `outlet_id`, and `type` (e.g., SUPPLIER, STOCKTAKE). > "Create a new SUPPLIER consignment in outlet 'out_9988'. Name it 'Q3 Winter Restock'. Once created, give me the new consignment ID so we can start adding products to it." ### List All Lightspeed Consignments With `list_all_lightspeed_consignments`, Claude can monitor the status of all active supply chain movements. It returns the `type`, `status` (OPEN, DISPATCHED, RECEIVED), `due_at` dates, and `supplier_id`. > "List all recent Lightspeed consignments. Filter out the ones that are already marked RECEIVED, and give me a summary of all OPEN supplier orders that are past their due date." To view the complete inventory of available tools and their exact JSON schemas, visit the [Lightspeed integration page](https://truto.one/integrations/detail/lightspeed). ## Workflows in Action Providing an LLM with individual tools is useful, but the real power of MCP is chaining these tools together to execute complex retail operations autonomously. Here are two real-world workflows. ### Workflow 1: VIP Customer Group Assignment Retailers often rely on AI agents to analyze purchase data and update loyalty structures. In this scenario, a store manager asks Claude to upgrade a specific customer to a VIP group. > "Look up the customer group ID for 'VIP Tier'. Then, find the customer record for Sarah Jenkins and update her profile to belong to that VIP group." Here is how Claude executes this multi-step process via the MCP server: ```mermaid sequenceDiagram participant User as Retail Manager participant Claude as Claude Desktop participant MCP as Lightspeed MCP Server participant API as Lightspeed API User->>Claude: "Look up the VIP group and assign Sarah Jenkins." Claude->>MCP: Call list_all_lightspeed_customer_groups MCP->>API: GET /api/2.0/customer_groups API-->>MCP: Returns groups (VIP Tier ID: grp_88) MCP-->>Claude: Returns JSON schema Claude->>MCP: Call list_all_lightspeed_customers (query: Sarah Jenkins) MCP->>API: GET /api/2.0/customers?search=Sarah Jenkins API-->>MCP: Returns customer (ID: cust_1122) MCP-->>Claude: Returns JSON schema Claude->>MCP: Call update_a_lightspeed_customer_by_id (cust_1122, {customer_group_id: "grp_88"}) MCP->>API: PUT /api/2.0/customers/cust_1122 API-->>MCP: 200 OK (Updated Customer) MCP-->>Claude: Returns updated profile Claude-->>User: "Sarah Jenkins has been successfully moved to the VIP Tier group." ``` ### Workflow 2: Auditing Supplier Consignments Managing inbound stock requires tracking what has been ordered versus what has actually arrived. An operations manager can use Claude to flag overdue shipments. > "List all of our active Lightspeed consignments. Identify any SUPPLIER orders that are still marked OPEN or DISPATCHED but were due before today. Then fetch the products inside the most overdue order so I can see what inventory we are missing." **Step-by-step execution:** 1. Claude calls `list_all_lightspeed_consignments` to pull the active order board. 2. It filters the returned JSON in memory, looking for `type: "SUPPLIER"` and checking `status` against current dates. 3. Identifying the most delayed consignment (e.g., ID: `con_7766`), Claude calls `list_all_lightspeed_consignment_products` passing `consignment_id: "con_7766"`. 4. Claude returns a natural language summary: "You have 3 overdue supplier orders. The oldest is 'Spring Apparel Delivery' (con_7766), which is missing 150 units of product ID prod_4433. Do you want me to flag this supplier?" ## Security and Access Control Giving an LLM access to your core retail database requires strict guardrails. Truto MCP servers include built-in security features that act at the token level, ensuring the LLM cannot exceed its intended authority. * **Method Filtering (`methods`):** Restrict the server to specific operation types. Setting `methods: ["read"]` ensures the LLM can only execute `get` and `list` operations. It cannot create orders or delete customers, preventing accidental data destruction. * **Tag Filtering (`tags`):** Scope the available tools to specific functional areas. By passing `tags: ["inventory"]`, the server will only expose product and consignment tools, hiding all customer and billing endpoints from the model. * **Secondary Authentication (`require_api_token_auth`):** For maximum security, enable this flag. The MCP URL alone will no longer grant access; the client must also pass a valid Truto API token in the `Authorization` header. This prevents unauthorized access if the MCP URL leaks in a config file. * **Time-To-Live (`expires_at`):** Generate short-lived MCP servers for temporary automation runs. By setting an ISO datetime, the server will automatically destroy itself when the task window closes. ## Moving Past Manual Integration Work Building an integration with Lightspeed Retail is complex. Handling the variant hierarchies, version-based syncing, and strict consignment rules requires constant engineering maintenance. By leveraging a managed MCP server via Truto, you abstract away the API lifecycle. The server automatically maps Lightspeed's complex JSON schemas into flat, LLM-friendly tool definitions, complete with query and body parameter mapping. You get secure, rate-limit-aware access to your retail data, allowing you to focus on building autonomous agents rather than debugging API endpoints.