Lightspeed MCP setup

A Lightspeed MCP setup connects mcp-core to a Lightspeed eCom (C-Series) webshop through its REST API, with an API key and secret. You need the Lightspeed entitlement and four env vars. Claude then reads products, variants, categories, brands, orders, customers and coupons. The tool is always read-only: it contains no code that writes to Lightspeed.

What do you need for a Lightspeed MCP setup?

You need a running mcp-core installation and the Lightspeed eCom add-on on the same license. No mcp-core yet? Follow the mcp-core install guide first.

• An active license with the tool:lightspeed entitlement, from the Lightspeed MCP server add-on.
• A Lightspeed eCom shop with API access. Lightspeed only offers API access on its Advanced and Professional subscriptions.
• An API key and API secret for that shop.
• A seat in My Account → MCP Self-hosted with the Lightspeed tool ticked.

This tool is for Lightspeed eCom C-Series, the webshop platform. It does not work with Lightspeed Retail (X-Series or R-Series), the point-of-sale products, which use a different API.

Bought the add-on after installing mcp-core? No reinstall and no new download. It is added to your license, and an email lists the env vars to fill in.

Where do you get the API key and secret for a Lightspeed MCP setup?

You create the API key in the back office of your Lightspeed eCom shop, which gives you a key and a secret. The tool only ever sends GET requests with them. The tool sends both values as HTTP Basic authentication: the key as user name, the secret as password.

You also need two other facts about the shop:

• The cluster. A shop lives on exactly one: EU at https://api.webshopapp.com, US at https://api.shoplightspeed.com. The wrong cluster fails, even with correct credentials. Ask Lightspeed support if you are not sure.
• The language code of the shop, such as nl or en. It becomes part of every request path.

Which env vars does the Lightspeed MCP setup use?

Four variables cover one shop; one JSON variable covers several. The .env in your download contains the four required lines, empty. There is no LIGHTSPEED_MODE.

LIGHTSPEED_BASE_URL=https://api.webshopapp.com
LIGHTSPEED_LANGUAGE=nl
LIGHTSPEED_API_KEY=your-api-key
LIGHTSPEED_API_SECRET=your-api-secret

Requests go to {base URL}/{language}/{resource}.json. You can also store these values in My Account → MCP Self-hosted → Tools. They are kept encrypted, a running mcp-core picks them up without a new download, and they override .env.

How do you connect several shops in one Lightspeed MCP setup?

Set LIGHTSPEED_CONNECTIONS to a JSON array with one object per shop. Each shop can sit on its own cluster and language. Once this is set, the four scalar variables are ignored.

LIGHTSPEED_CONNECTIONS=[{"id":"shop-a","label":"Main shop","baseUrl":"https://api.webshopapp.com","language":"nl","apiKey":"...","apiSecret":"..."},{"id":"shop-b","baseUrl":"https://api.shoplightspeed.com","language":"en","apiKey":"...","apiSecret":"..."}]

Every entry needs id, baseUrl, language, apiKey and apiSecret; label is optional. With two or more shops, both tools get a required store parameter and Claude picks the shop by id.

Which tools does Claude see after the Lightspeed MCP setup?

Claude gets two tools, in every mode. Picking read-write for Lightspeed on a seat changes nothing, because the tool has no write tools to add. Entitlements vs. tool modes explains how modes work for the other add-ons.

• lightspeed_list_endpoints: lists the endpoints Claude can query, with a short description.
• lightspeed_get: a GET request on one allowed endpoint, with optional query parameters such as page or since_id.

Allowed endpoints are products, variants, categories, brands, orders, customers and coupons. Claude can add a numeric id for one record, such as orders/1042, and orders/1042/products returns that order’s line items. Results are capped at 50 items per page; Claude uses page for more. Very long responses are cut at 20,000 characters and end with “(truncated)”.

How do you restart and test the Lightspeed MCP setup?

Run the update script from the folder you unzipped:

./mcp-update.sh

If you just bought the add-on, fetch the new entitlement right away:

docker exec mcp-core npm run refresh-license

In Claude, call mcp_status. It shows the license state, your seat and the tools it can use. Then ask “show the 10 most recent orders from Lightspeed” as a first test of the Lightspeed MCP setup. If several clients connect, check which token belongs to which seat in MCP seats.

Which errors come up during a Lightspeed MCP setup?

These messages come from the tool itself.

• No Lightspeed tools at all: the log says “No Lightspeed store is configured”. Fill in all four scalar vars or LIGHTSPEED_CONNECTIONS, then run ./mcp-update.sh.
• “LIGHTSPEED_CONNECTIONS is not valid JSON” or “is missing baseUrl/language/apiKey/apiSecret”: fix the array, on one line, with double quotes.
• “Endpoint ‘…’ is not allowed”: Claude asked for something outside the list. It should call lightspeed_list_endpoints first.
• “Multiple Lightspeed stores are configured — pass the store parameter” or “Unknown Lightspeed store”: wrong or missing id.
• “Lightspeed [id] API error” with a status code: check the key and secret, and whether LIGHTSPEED_BASE_URL is the cluster your shop is on.

The Lightspeed MCP setup works when lightspeed_get returns your products. The other add-ons are covered in the MCP setup guides.