Serwer MCP dla CS-Cart, instrukcja krok po kroku

Jak to działa

Serwer MCP jest osobną usługą, która stoi obok sklepu i rozmawia z nim przez REST API CS-Carta. Asystent AI nie łączy się ze sklepem bezpośrednio: wysyła pytanie do serwera, serwer zamienia je na wywołanie API, pobiera dane i oddaje je w postaci, którą model rozumie. Dzięki temu w samym sklepie nie zmienia się żaden plik rdzenia, a jedyną rzeczą instalowaną po stronie CS-Carta jest dodatek ss_mcp, który dokłada do API kilka gotowych zestawień.

W standardowej konfiguracji serwer działa wyłącznie do odczytu. Odpowiada na pytania o produkty, kategorie, zamówienia, klientów i sprzedaż, ale niczego w sklepie nie zmienia. Każde połączenie wymaga tokenu dostępu, a token można w dowolnej chwili unieważnić.

Co będzie potrzebne

• Sklep CS-Cart albo Multi-Vendor w wersji 4.12.1 lub nowszej (to wymaganie dodatku ss_mcp; sam serwer korzysta wyłącznie z REST API).
• Dostęp do panelu administratora z prawem zakładania administratorów.
• Adres serwera MCP i token dostępu. Przy instancji hostowanej przez nas, także demonstracyjnej, oba dostajesz od nas mailem, przy czym token zawsze osobną wiadomością.
• Klient MCP: Claude Desktop, claude.ai w przeglądarce albo n8n z węzłem MCP Client.

Krok 1. Użytkownik API w sklepie

Serwer loguje się do sklepu jako konkretny użytkownik, więc najlepiej założyć do tego osobne konto administratora, niezwiązane z żadną osobą z zespołu. Takie konto da się później wyłączyć jednym ruchem, bez wpływu na resztę panelu.

1. W panelu wejdź w Klienci > Administratorzy i dodaj nowego administratora, na przykład z adresem mcp@twojsklep.pl. Zapisz profil.
2. Otwórz profil ponownie. Zakładka Dostęp do API sklepu pojawia się dopiero po pierwszym zapisaniu konta.
3. Na tej zakładce zaznacz Dostęp API dla tego użytkownika. Sklep wygeneruje klucz API.
4. Skopiuj klucz od razu. Po zapisaniu zmian panel nie pokaże go już nigdy więcej, a zgubiony klucz można tylko zastąpić nowym.
5. Sprawdź strefę czasową sklepu w Ustawienia > Wygląd, pole Strefa czasowa. Serwer musi znać tę samą strefę, inaczej daty zamówień w odpowiedziach przesuną się o różnicę czasu.

Konto musi pozostać aktywne. Wyłączony administrator dostaje od API odmowę, a serwer zgłasza wtedy, że sklep odrzucił uwierzytelnienie.

W Multi-Vendor klucz API może otrzymać administrator. Konto administratora widzi dane wszystkich sprzedawców, łącznie z zamówieniami i klientami, więc decyzję o podłączeniu warto podjąć świadomie, tak jak przy każdej integracji z pełnym dostępem.

Jeśli serwer hostujemy my, przekaż nam adres sklepu, e-mail tego administratora, klucz API i strefę czasową. Najlepiej klucz osobną wiadomością.

Krok 2. Dodatek ss_mcp

Rdzeniowe API CS-Carta nie oddaje sprzedaży w podziale na produkty, wydatków pojedynczego klienta ani gotowej sumy obrotu. Dodatek ss_mcp dokłada cztery zestawienia tylko do odczytu, liczone tymi samymi funkcjami rdzenia, z których korzysta panel administracyjny:

• statystyki sprzedaży z porównaniem do poprzedniego okresu,
• ranking najlepiej sprzedających się produktów,
• podsumowanie zakupów pojedynczego klienta,
• porzucone koszyki.

Instalacja:

1. Wejdź w Dodatki > Zarządzanie dodatkami i wybierz Instalacja manualna.
2. Wskaż plik zip z dodatkiem i potwierdź instalację.
3. Dodatek pojawi się na liście jako aktywny. W menu Klienci przybędzie pozycja Źródło danych MCP.

Dodatek nie ma ustawień, które trzeba wypełnić. W konfiguracji są tylko pole informacyjne i opcjonalne logowanie zapytań, przydatne przy diagnozie. Kwotę zapłaconą dodatek liczy według statusów zamówień, które w sklepie mają zaznaczone otrzymanie płatności, więc korzysta z tego, co już jest skonfigurowane.

Serwer działa również bez dodatku, ale wtedy część odpowiedzi jest uboższa. Ranking produktów i podsumowanie klienta odpowiedzą informacją o braku dodatku, obrót serwer policzy samodzielnie z najwyżej 500 zamówień i bez porównania okresów, a porzucone koszyki będą pochodzić z rdzeniowego API z mniejszą dokładnością.

Krok 3. Podłączenie klienta MCP

Do podłączenia potrzebne są dwie rzeczy z naszego maila: adres serwera, na przykład https://mcp.cs-cart.com.pl/demo/twoj-sklep/mcp, oraz token. Token przekazuje się w nagłówku Authorization w postaci Bearer i spacja, a po niej token.

Claude Desktop

Claude Desktop łączy się ze zdalnym serwerem przez pomocnika mcp-remote, który wymaga zainstalowanego Node.js. W aplikacji wejdź w Settings > Developer > Edit Config i dopisz do pliku claude_desktop_config.json:

{
  "mcpServers": {
    "sklep-cscart": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "ADRES_SERWERA",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer TWOJ_TOKEN" }
    }
  }
}

W miejsce ADRES_SERWERA wpisz adres z maila, a w miejsce TWOJ_TOKEN token. Nagłówek jest celowo zapisany bez spacji po dwukropku, a sam token siedzi w zmiennej środowiskowej, bo na Windows spacja w argumencie potrafi rozbić polecenie. Po zapisaniu pliku zamknij Claude Desktop całkowicie i uruchom ponownie. Narzędzia sklepu pojawią się w oknie rozmowy.

claude.ai w przeglądarce

W Settings > Connectors wybierz Add custom connector i podaj adres serwera. Jeśli w oknie dodawania jest sekcja Request headers, dodaj nagłówek authorization o wartości Bearer TWOJ_TOKEN, wpisując słowo Bearer samodzielnie. Ta sekcja jest na razie dostępna tylko na części kont. Gdy jej nie ma, połączenie z tokenem nie zadziała i zostaje Claude Desktop albo n8n.

n8n

Dodaj do workflow węzeł MCP Client i ustaw w nim adres serwera, transport HTTP Streamable oraz uwierzytelnianie Bearer Auth z tokenem zapisanym w danych uwierzytelniających. Węzeł można podpiąć jako narzędzie agenta AI albo wywoływać wprost, na przykład w raporcie wysyłanym co poniedziałek.

Krok 4. Pierwsze pytania

Zacznij od sprawdzenia połączenia. Zapytaj asystenta, czy połączenie ze sklepem działa. Wywoła wtedy narzędzie health_check, które podaje, czy sklep odpowiada, i jak szybko. Potem możesz pytać zwykłym językiem:

• Jaki był obrót w tym miesiącu w porównaniu z poprzednim?
• Które produkty sprzedawały się najlepiej w tym roku?
• Pokaż ostatnie zamówienia i ich statusy.
• Ile wydał klient o adresie jan@example.com i co kupował najczęściej?
• Którzy klienci porzucili koszyk i na jaką kwotę?
• Jaki jest stan magazynowy i cena produktu o nazwie zawierającej słowo kurtka?

Asystent sam dobiera narzędzia i ich kolejność, więc jedno pytanie potrafi uruchomić kilka z nich po kolei.

Co potrafi serwer

Narzędzie	Na jakie pytania odpowiada	Dodatek ss_mcp
health_check	czy połączenie ze sklepem działa	nie
get_products	wyszukiwanie produktów: nazwa, cena, stan, status	nie
get_product_details	pełne dane produktu, w tym kod, ceny, waga i opis	nie
get_categories	drzewo kategorii z liczbą produktów	nie
get_product_reviews	recenzje i oceny produktu (wymaga rdzeniowego dodatku Komentarze i Opinie)	nie
get_orders	lista zamówień z filtrem statusu, e-maila i okresu	nie
get_order_details	szczegóły zamówienia: produkty, klient, adres dostawy, metoda płatności, sumy z kosztem wysyłki	nie
get_customer_info	dane klienta po e-mailu albo numerze	nie
get_store_stats	liczba produktów i zamówień, obrót, porównanie okresów	zalecany
get_abandoned_carts	porzucone koszyki: klient, e-mail, wartość, liczba produktów, wiek koszyka	zalecany
get_top_products	ranking produktów według sprzedaży	wymagany
get_customer_summary	historia zakupów i wydatki klienta	wymagany

Pytania o sprzedaż obejmują okresy znane z panelu CS-Carta: dziś i wczoraj, ten i poprzedni tydzień, ten i poprzedni miesiąc, ten i poprzedni rok, a także ostatnią dobę, ostatnie 7 i ostatnie 30 dni. Bez wskazania okresu ranking i statystyki dotyczą bieżącego miesiąca albo całej historii, zależnie od narzędzia. Dowolnego zakresu dat od do serwer na razie nie obsługuje.

Obrót nie obejmuje zamówień anulowanych, odrzuconych, nieudanych ani niezakończonych. Listy produktów, zamówień i koszyków zwracają najwyżej 100 pozycji naraz, więc przy dużych zestawieniach lepiej pytać o konkretny okres albo filtr.

Multi-Vendor

Na kluczu administratora serwer widzi cały marketplace i tak go testujemy. Zamówienie złożone u kilku sprzedawców nie jest liczone podwójnie: zestawienia biorą pod uwagę zamówienia sprzedawców, a nie zamówienie nadrzędne, które je grupuje. Porzucone koszyki są dostępne tylko dla administratora, bo w Multi-Vendor koszyk nie jest przypisany do sprzedawcy. Gdy dodatek obsługuje zapytanie sprzedawcy, statystyki, ranking i podsumowanie klienta ograniczają się do jego własnej firmy.

Bezpieczeństwo

• Serwer działa tylko do odczytu. Narzędzia zapisu, czyli zmiana statusu zamówienia i stanu magazynowego, istnieją, ale są wyłączone i nie pojawiają się na liście narzędzi, dopóki nie włączymy ich na wyraźne życzenie.
• Każde połączenie wymaga tokenu. Token ma termin ważności, a unieważniony przestaje działać natychmiast, bez restartu serwera. Na serwerze przechowujemy wyłącznie jego skrót kryptograficzny.
• Serwer nie ma własnej bazy danych i nie kopiuje zawartości sklepu. Pobiera tylko to, o co pada pytanie.
• Dostęp do sklepu odcinasz u siebie w każdej chwili, wyłączając administratora z kroku 1 albo jego dostęp do API.

Rozwiązywanie problemów

Asystent nie widzi narzędzi sklepu. W Claude Desktop najczęściej przyczyną jest błąd składni w pliku konfiguracyjnym albo brak Node.js. Sprawdź, czy plik jest poprawnym JSON-em, i uruchom aplikację ponownie.

Serwer odpowiada komunikatem Wymagany naglowek Authorization: Bearer <token>. albo Nieprawidlowy token. Token nie dociera albo ma literówkę. Sprawdź, czy przed tokenem stoi słowo Bearer i jedna spacja.

Serwer odpowiada Token wygasl. Termin ważności minął. Przy demo napisz do nas, przedłużymy je bez zmiany tokenu.

Narzędzie zwraca Sklep odrzucil uwierzytelnienie (HTTP 401/403). Klucz API jest nieaktualny, administrator został wyłączony albo zmienił się jego e-mail. Wygeneruj nowy klucz w profilu administratora i przekaż go nam.

Narzędzie zwraca Blad polaczenia ze sklepem albo health_check pokazuje brak połączenia. Sklep jest niedostępny albo blokuje ruch do API, na przykład zaporą lub ochroną przed botami. Sprawdź, czy adres sklepu z dopiskiem /api otwiera się z zewnątrz.

Ranking produktów albo podsumowanie klienta odpowiada, że wymaga dodatku. Dodatek ss_mcp nie jest zainstalowany albo jest wyłączony. Wróć do kroku 2.

Daty zamówień są przesunięte o kilka godzin. Strefa czasowa serwera nie zgadza się ze strefą sklepu. Podaj nam strefę z Ustawienia > Wygląd.

Co dalej

Więcej o tym, czym jest MCP i co przemyśleć przed podłączeniem AI do danych sklepu, piszemy w artykule Serwer MCP dla sklepu. Opis usługi i cennik znajdziesz na stronie serwera MCP dla CS-Cart. Jeśli chcesz wypróbować serwer na swoim sklepie, napisz do nas, a uruchomimy demo na naszej infrastrukturze.