Serwer MCP

Hostowany serwer MCP ItemShop: narzędzia do strony, katalogu, zamówień i rabatów dla agentów AI.

ItemShop udostępnia serwer Model Context Protocol, dzięki któremu agent AI (Claude Code, Codex, OpenCode, Cursor, Gemini CLI…) może pracować na Twoim sklepie: edytować pliki strony, budować i publikować podgląd, zarządzać produktami i rabatami.

Adres	https://itemshop.dev/api/v2/mcp
Transport	streamable HTTP, bezstanowy (GET zwraca 405)
Uwierzytelnienie	Authorization: Bearer iswt_… (token workspace)
Mostek stdio	npx -y @itemshop/mcp (zmienna ITEMSHOP_TOKEN)

Konfigurację konkretnego agenta znajdziesz w Podłączanie agentów.

​

Token workspace

W panelu: Workspace → MCP → Nowy token. Wybierz tylko zakresy, których agent potrzebuje. Token (prefiks iswt_) widać tylko raz — trzymaj go w zmiennej środowiskowej, nie w commitowanym pliku:

export ITEMSHOP_TOKEN=iswt_...

Zakres	Pozwala
site:read	Czytać pliki, rewizje, buildy i src/site.config.ts
site:write	Edytować szkic, zatwierdzać/odrzucać go, uruchamiać buildy, podglądy i publikację (obejmuje site:read)
catalog:read	Czytać produkty i serwery
catalog:write	Tworzyć i zmieniać produkty (obejmuje catalog:read)
orders:read	Czytać zamówienia (bez e-maili, IP i danych płatności)
discounts:write	Rabaty i vouchery — odczyt i zapis
stats:read	Czytać statystyki sprzedaży

Token nie może dać więcej, niż ma jego twórca w zespole sklepu — jeśli twórca straci dostęp, token przestaje działać.

​

Grupy narzędzi

Właściciel ustawia w Workspace → MCP dla każdej grupy tryb: wyłączona / odczyt / zapis. Dotyczy to wszystkich tokenów. Efektywny dostęp wywołania to mniejsze z dwóch: ustawienie grupy i zakresy tokenu.

Grupa	Narzędzia	Zakres odczyt / zapis	Domyślnie
Kontekst	get_shop_context	dowolny token	zawsze
Pliki strony	get_site, list_files, read_file, search_files, list_revisions, write_file, apply_patch, delete_file, commit_draft, discard_draft	site:read / site:write	zapis
Buildy i publikacje	get_build, start_build, create_preview, promote_deployment	site:read / site:write	zapis
Wygląd	get_site_config, update_site_config	site:read / site:write	zapis
Katalog produktów	list_products, get_product, create_product, update_product	catalog:read / catalog:write	odczyt
Zamówienia	list_orders	orders:read / —	wyłączona
Rabaty i vouchery	list_discounts, create_discount, update_discount, list_vouchers, create_vouchers	discounts:write / discounts:write	wyłączona
Statystyki	get_stats	stats:read / —	odczyt

Zamówienia i statystyki nie mają trybu zapisu. Zamówienia są domyślnie wyłączone, bo zawierają dane kupujących — włączasz je świadomie.

Serwer udostępnia też zasoby itemshop://shop i itemshop://site/files/{path} (szkic) oraz dwa prompty: change_look i add_product.

​

Zabezpieczenia

• Zmiany plików trafiają do szkicu — na produkcji nic się nie zmienia, dopóki build nie zostanie opublikowany.
• promote_deployment i discard_draft wymagają jawnego confirm: true. Publikację na produkcję możesz zarezerwować dla panelu (Workspace → Publikacje) — wtedy agent udostępnia tylko link do podglądu. Przy włączonej polityce (domyślnie) promote_deployment zwraca 403 WORKSPACE_PRODUCTION_REQUIRES_APPROVAL.
• Zmiany produktów przechodzą tę samą walidację co panel.
• Każde wywołanie trafia do logu aktywności Workspace (źródło mcp).
• Limity per token: 240 żądań na minutę, w tym 60 zapisów na minutę. Nieudane uwierzytelnienia są limitowane per IP.
• Podejrzewasz wyciek? Unieważnij token w panelu — działa natychmiast.

​

Mostek stdio

Jeśli agent obsługuje tylko lokalne serwery stdio, użyj @itemshop/mcp. Przekazuje każdą wiadomość do serwera hostowanego, więc ma te same narzędzia, zakresy i limity.

npx -y @itemshop/mcp [--url <url>] [--api-base <url>] [--profile <nazwa>] [--token <iswt_…>]

Ustawienie	Kolejność
Adres serwera	--url › ITEMSHOP_MCP_URL › <baza API>/mcp
Baza API	--api-base › ITEMSHOP_API_BASE › profil z itemshop login › https://itemshop.dev/api/v2
Token	--token › ITEMSHOP_TOKEN › ITEMSHOP_MCP_TOKEN › ITEMSHOP_API_KEY › profil z itemshop login

Mostek przyjmuje wyłącznie tokeny workspace (iswt_…) i nie wysyła tokenu przez zwykłe HTTP (poza localhost). Diagnostyka idzie na stderr, stdout niesie tylko wiadomości MCP.

„ItemShop rejected the workspace token”

Token został unieważniony, wygasł albo jego twórca stracił dostęp do sklepu. Utwórz nowy.

„No workspace token”

Ustaw ITEMSHOP_TOKEN w środowisku, w którym agent uruchamia mostek.

Agent widzi mniej narzędzi niż oczekiwano

Sprawdź zakresy tokenu i tryby grup w Workspace → MCP. Przycisk Test połączenia pokazuje, co faktycznie jest dostępne.

Skille agentowe

Wiedza o ItemShop dla agenta.

Podłączanie agentów

Konfiguracja Claude Code, Codex, Cursor.