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. 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 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/ or explore our broader architectural overview on /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.

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, 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:

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:

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

{
  "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.

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:

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.