Connect Lightspeed to ChatGPT: Manage Retail Stock and Sales

If you want to connect Lightspeed to ChatGPT so your AI agents can manage retail inventory, draft supplier consignments, track daily sales, and update customer loyalty balances, you need a Model Context Protocol (MCP) server. This infrastructure layer translates natural language requests from the Large Language Model (LLM) into structured, authenticated JSON-RPC calls against the Lightspeed API.

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

Building a custom MCP server for a complex Point of Sale (POS) system like Lightspeed Retail (X-Series) is an engineering slog. You have to handle complex nested variant structures, strictly typed payload definitions, and demanding pagination schemes. Instead of writing and hosting this boilerplate integration code yourself, you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL based directly on the API's documentation.

This guide breaks down exactly how to use Truto to generate an MCP server for Lightspeed, connect it to ChatGPT, and execute multi-step retail operations using natural language.

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::

The Engineering Reality of the Lightspeed API

Building a static MCP schema for Lightspeed is exceptionally difficult because the underlying API is designed for high-volume retail synchronization rather than simple CRUD operations. If you decide to build a custom MCP server, you own the entire integration lifecycle. Here are the specific challenges you will encounter when working with the Lightspeed Retail (X-Series) API:

Sequential Versioning Instead of Timestamps

Lightspeed heavily relies on a version integer for data synchronization rather than standard updated_at timestamps. Every record - whether it is a customer, product, or sale - gets a sequentially incremented version number when modified. If an LLM needs to query "all customers modified today", it cannot simply pass a date range to the list endpoint. Your MCP server must understand version bounds (after and before) and maintain cursor state across tool calls to retrieve the correct delta.

Nested Product Variants and Matrices

Retail inventory is rarely flat. A single call to fetch a product might return a standalone item, a parent product matrix, or a specific variant (like a medium red shirt). Products contain fields like has_variants and variant_parent_id that dictate how stock is structured. If your AI agent tries to delete a product by ID, and that ID belongs to a variant, the API will only remove that specific variant from its family. Your MCP tool schemas must explicitly define these relationships, or the LLM will hallucinate inventory updates and break your catalog structure.

Consignment State Machines

Managing stock via the API requires interacting with Consignments. A consignment acts as a state machine for SUPPLIER, OUTLET, STOCKTAKE, or RETURN orders. You cannot simply create a consignment in a RECEIVED or DISPATCHED state. The LLM must first create the draft consignment, add products to it in bulk, and then update its status. If your MCP tools do not strictly enforce these state transitions, the API will reject the payloads.

Handling Rate Limits and 429 Errors

When an AI agent executes a complex workflow, it can quickly burn through API rate limits. It is critical to understand how Truto handles these boundaries: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Lightspeed API returns an HTTP 429 status code, 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 orchestrator - is entirely responsible for detecting the 429, reading the reset headers, and implementing the appropriate backoff and retry logic.

How to Generate a Lightspeed MCP Server

Truto creates MCP tools dynamically based on integration resource documentation. Every server is scoped to a single integrated account (a specific tenant's connected instance of Lightspeed). This means the generated MCP server URL is fully self-contained and handles all authentication routing.

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

Method 1: Via the Truto UI

If you prefer a visual setup, you can generate the server directly from your dashboard:

1. Navigate to the Integrated Accounts page and select your connected Lightspeed account.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can assign a human-readable name, filter by specific methods (like read or write), or restrict access by tags (like products or sales).
5. Click Save, and immediately copy the generated MCP server URL. Treat this URL like a production secret.

Method 2: Via the Truto API

For automated deployments, you can provision MCP servers programmatically. This endpoint verifies that the integration has tools available, generates a secure token, hashes it for storage, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

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": "Lightspeed Retail Stock Manager",
    "config": {
      "methods": ["read", "write"],
      "tags": ["inventory", "sales", "customers"]
    }
  }'

The response will contain the secure endpoint URL:

{
  "id": "mcp_abc123",
  "name": "Lightspeed Retail Stock Manager",
  "config": { "methods": ["read", "write"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the Lightspeed MCP Server to ChatGPT

Once you have the url from Truto, connecting it to ChatGPT takes only a few steps. You can configure this directly in the ChatGPT interface or via a local configuration file for custom desktop deployments.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education, you can add custom connectors natively:

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle to unlock MCP support.
3. Under the MCP servers / Custom connectors section, click to add a new server.
4. Enter a recognizable Name (e.g., "Lightspeed POS").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Save. ChatGPT will immediately connect, perform the JSON-RPC handshake, and index the available Lightspeed tools.

Method B: Via Manual Config File

If you are running a custom MCP client architecture or integrating into a local agent framework, you can connect to the remote Truto server using the official Server-Sent Events (SSE) transport adapter.

Add the following configuration to your MCP client's JSON settings file:

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

This configuration instructs the client to proxy standard standard I/O requests over HTTP to Truto's remote JSON-RPC endpoint.

Lightspeed Hero Tools for ChatGPT

Truto exposes dozens of proxy APIs for Lightspeed, mapping native endpoints to predictable tool structures. Below are the highest-leverage hero tools for managing retail operations.

get_single_lightspeed_product_by_id

Retrieves a complete product record, including its SKU, retail price, supply price, brand ID, and variant matrix details. This tool is the foundation for any inventory lookup workflow.

"Look up the details for product ID 938472. Tell me the current retail price and check if it is part of a variant family."

update_a_lightspeed_product_by_id

Modifies an existing product's metadata in the X-Series catalog. You must supply the product ID. This is typically used by agents to adjust pricing, update SKUs, or correct product names after analyzing market data.

"Update product ID 938472 to reflect a new retail price of 49.99."

list_all_lightspeed_sales

Fetches a paginated collection of sale records. It returns core invoice data including the status, state, invoice number, customer ID, and outlet ID. This tool is critical for end-of-day reconciliation.

"Show me a list of all recent sales from outlet ID 14. Extract the invoice numbers and the associated customer IDs."

create_a_lightspeed_customer

Creates a new customer profile in the POS system. The tool requires a first_name and last_name, and returns the newly generated customer ID, loyalty balance, and version integer.

"Create a new customer profile for Jane Doe. Add her email address as jane.doe@example.com and assign her to customer group ID 5."

create_a_lightspeed_consignment

Drafts a new consignment order. Consignments are required to move stock into or out of the system (SUPPLIER, OUTLET, STOCKTAKE, or RETURN). You must provide a name, outlet ID, and type. The API enforces that consignments are created in a draft state.

"Draft a new SUPPLIER consignment named 'Fall Restock 2026' for outlet ID 14."

lightspeed_consignment_products_bulk_update

Adds or updates products inside a specific consignment. Instead of making 50 separate API calls, the LLM passes an array of product IDs and quantities, returning a map of applied counts and received values.

"Add 50 units of product ID 938472 and 25 units of product ID 112233 to consignment ID 884422."

For the complete tool inventory and granular JSON Schema definitions, view the Lightspeed integration page.

Workflows in Action

Connecting a single endpoint is easy, but retail operations require multi-step orchestration. Because Truto's tools share a flat input namespace and standardized JSON Schemas, ChatGPT can chain these operations together autonomously.

Workflow 1: Automated Supplier Restocking

When stock runs low, an AI agent can analyze a product and immediately draft a supplier order to replenish the exact required variants.

"Check the details of product ID 88372. If it is a standalone product, draft a new SUPPLIER consignment for outlet 22 named 'Emergency Restock', and add 100 units of the product to it."

Step-by-step execution:

1. get_single_lightspeed_product_by_id: ChatGPT fetches the product metadata to verify has_variants is false.
2. create_a_lightspeed_consignment: ChatGPT generates a new supplier order, retrieving the new consignment_id.
3. lightspeed_consignment_products_bulk_update: ChatGPT attaches an array containing the product ID and a count of 100 to the newly drafted consignment.

The user receives a confirmation that the supplier order is staged and ready for final review by a store manager.

Workflow 2: VIP Customer Profile Management

Agents can act as high-speed retail support assistants, instantly locating shoppers and updating their centralized profiles.

"Find the customer record for John Smith. Retrieve his ID and current loyalty balance, then update his phone number to 555-0199."

Step-by-step execution:

1. list_all_lightspeed_customers: ChatGPT queries the customer directory, parsing the response to locate the ID for John Smith and reading his loyalty_balance.
2. update_a_lightspeed_customer_by_id: ChatGPT issues a write command targeting John Smith's ID, passing the new phone number in the body schema.

The agent responds with John's current loyalty point total and confirms the contact information has been successfully updated in the POS.

sequenceDiagram
  participant User as User Prompt
  participant LLM as ChatGPT
  participant MCP as Truto MCP Server
  participant API as Lightspeed API

  User->>LLM: "Find John Smith and update phone to 555-0199"
  LLM->>MCP: call list_all_lightspeed_customers
  MCP->>API: GET /api/2.0/customers
  API-->>MCP: Returns customer array
  MCP-->>LLM: Normalized customer records
  LLM->>MCP: call update_a_lightspeed_customer_by_id
  MCP->>API: PUT /api/2.0/customers/{id}
  API-->>MCP: Returns updated record
  MCP-->>LLM: Success confirmation
  LLM-->>User: "John's profile updated. Loyalty balance: 450."

Security and Access Control

Exposing an enterprise POS system to an LLM requires strict security boundaries. Truto MCP servers support configuration parameters that lock down exactly what the model can touch:

• Method filtering: By setting config.methods to ["read"] during server creation, you completely disable the model's ability to execute create, update, or delete tools. The LLM can analyze sales data but cannot alter inventory.
• Tag filtering: Using config.tags, you can isolate domains. Specifying ["sales"] ensures the server only exposes tools related to transactions, hiding the customer directory and supplier configurations entirely.
• require_api_token_auth: If set to true, possessing the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, adding a mandatory secondary authentication layer.
• expires_at: For temporary access - such as an auditing script or a contractor's agent - you can supply an ISO datetime. Once reached, a durable background job automatically revokes the token and purges the key-value cache, terminating the server instantly.

Moving from Manual Tasks to Autonomous Retail

Connecting Lightspeed to ChatGPT via an MCP server turns a static Point of Sale system into a programmable retail engine. Instead of forcing store managers to navigate complex UIs to draft consignments, run stocktakes, or update customer records, AI agents can execute these workflows conversationally.

By leveraging Truto's dynamic tool generation, you bypass the friction of writing API wrappers, dealing with version cursors, and maintaining OAuth state. You ship retail automation faster, relying on a unified infrastructure layer that scales with your agentic workflows.