Lightspeed MCP instellen

Bij het instellen van Lightspeed MCP koppel je mcp-core aan een Lightspeed eCom-webshop (C-Series) via de REST API, met een API-key en secret. Je hebt de Lightspeed-entitlement en vier env-variabelen nodig. Claude leest daarna producten, varianten, categorieën, merken, bestellingen, klanten en kortingscodes. De tool is altijd read-only: hij bevat geen code die naar Lightspeed schrijft.

Wat heb je nodig om Lightspeed MCP in te stellen?

Je hebt een draaiende mcp-core-installatie nodig en de Lightspeed eCom-add-on op dezelfde licentie. Nog geen mcp-core? Volg dan eerst de installatiehandleiding voor mcp-core.

• Een actieve licentie met de entitlement tool:lightspeed, uit de add-on Lightspeed MCP-server.
• Een Lightspeed eCom-shop met API-toegang. Lightspeed biedt API-toegang alleen bij de abonnementen Advanced en Professional.
• Een API-key en API-secret voor die shop.
• Een seat in Mijn account → MCP Self-hosted met de Lightspeed-tool aangevinkt.

Deze tool is voor Lightspeed eCom C-Series, het webshopplatform. Hij werkt niet met Lightspeed Retail (X-Series of R-Series), de kassaproducten, die een andere API gebruiken.

Heb je de add-on gekocht nadat je mcp-core installeerde? Dan is er geen herinstallatie en geen nieuwe download nodig. Hij wordt aan je licentie toegevoegd, en een e-mail noemt de env-variabelen die je moet invullen.

Waar haal je de API-key en secret vandaan?

Je maakt de API-key aan in de backoffice van je Lightspeed eCom-shop; daar krijg je een key en een secret. De tool stuurt er alleen GET-requests mee. Beide waarden gaan mee als HTTP Basic-authenticatie: de key als gebruikersnaam, de secret als wachtwoord.

Je hebt ook nog twee andere gegevens over de shop nodig:

• Het cluster. Een shop staat op precies één cluster: EU op https://api.webshopapp.com, VS op https://api.shoplightspeed.com. Het verkeerde cluster faalt, ook met juiste gegevens. Vraag het Lightspeed-support als je het niet zeker weet.
• De taalcode van de shop, zoals nl of en. Die wordt onderdeel van elk requestpad.

Welke env-variabelen gebruikt Lightspeed MCP?

Vier variabelen dekken één shop; één JSON-variabele dekt er meerdere. De .env in je download bevat de vier verplichte regels, leeg. Er is geen 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 gaan naar {base URL}/{language}/{resource}.json. Je kunt deze waarden ook opslaan in Mijn account → MCP Self-hosted → Tools. Ze worden versleuteld bewaard, een draaiende mcp-core pikt ze op zonder nieuwe download, en ze gaan vóór .env.

Hoe koppel je meerdere shops in één installatie?

Zet LIGHTSPEED_CONNECTIONS op een JSON-array met één object per shop. Elke shop kan op een eigen cluster en taal staan. Zodra dit is ingesteld, worden de vier losse variabelen genegeerd.

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":"..."}]

Elk item heeft id, baseUrl, language, apiKey en apiSecret nodig; label is optioneel. Met twee of meer shops krijgen beide tools een verplichte parameter store en kiest Claude de shop op id.

Welke tools ziet Claude na het instellen van Lightspeed MCP?

Claude krijgt twee tools, in elke modus. Lezen en schrijven kiezen voor Lightspeed op een seat verandert niets, omdat de tool geen schrijftools heeft om toe te voegen. Entitlements vs. toolmodi legt uit hoe modi werken bij de andere add-ons.

• lightspeed_list_endpoints: toont de endpoints die Claude kan bevragen, met een korte omschrijving.
• lightspeed_get: een GET-request op één toegestaan endpoint, met optionele queryparameters zoals page of since_id.

Toegestane endpoints zijn products, variants, categories, brands, orders, customers en coupons. Claude kan een numeriek id toevoegen voor één record, zoals orders/1042, en orders/1042/products geeft de orderregels van die bestelling. Resultaten zijn begrensd op 50 items per pagina; voor meer gebruikt Claude page. Erg lange antwoorden worden afgekapt op 20.000 tekens en eindigen met “(truncated)”.

Hoe herstart en test je Lightspeed MCP?

Draai het updatescript vanuit de map die je hebt uitgepakt:

./mcp-update.sh

Heb je de add-on net gekocht, haal de nieuwe entitlement dan direct op:

docker exec mcp-core npm run refresh-license

Roep in Claude mcp_status aan. Dat toont de licentiestatus, je seat en de tools die die kan gebruiken. Vraag daarna “toon de 10 meest recente bestellingen uit Lightspeed” als eerste test. Verbinden meerdere clients, controleer dan in MCP-seats welk token bij welke seat hoort.

Welke foutmeldingen kom je tegen bij het instellen van Lightspeed MCP?

Deze meldingen komen van de tool zelf.

• Helemaal geen Lightspeed-tools: het log meldt “No Lightspeed store is configured”. Vul alle vier losse variabelen of LIGHTSPEED_CONNECTIONS in en draai daarna ./mcp-update.sh.
• “LIGHTSPEED_CONNECTIONS is not valid JSON” of “is missing baseUrl/language/apiKey/apiSecret”: corrigeer de array, op één regel, met dubbele aanhalingstekens.
• “Endpoint ‘…’ is not allowed”: Claude vroeg om iets buiten de lijst. Het moet eerst lightspeed_list_endpoints aanroepen.
• “Multiple Lightspeed stores are configured — pass the store parameter” of “Unknown Lightspeed store”: verkeerd of ontbrekend id.
• “Lightspeed [id] API error” met een statuscode: controleer de key en secret, en of LIGHTSPEED_BASE_URL het cluster is waar je shop op staat.

Lightspeed MCP is goed ingesteld als lightspeed_get je producten teruggeeft. De andere add-ons staan in de MCP-installatiehandleidingen.