Připojení AI asistenta (MCP) | Dokumentace SHOPZI

Obsah dokumentace

Co je MCP a k čemu je

MCP (Model Context Protocol) je jednotný způsob, jak dát AI asistentovi, kterého už používáte, přímý přístup k datům vašeho obchodu. Místo abyste vypisovali exporty a kopírovali je do chatu, zeptáte se ve svém asistentovi „kolik mám produktů bez popisu“ a on si data sám dotáhne odsud.

Karta Připojení klienta: adresy serveru MCP a REST API, přepínač Claude Code, Cursor, VS Code a Jiný klient a příkaz ke zkopírování. — Karta Připojení klienta v Nastavení → API a MCP: adresa serveru MCP a hotový příkaz pro Claude Code, Cursor, VS Code nebo jiného klienta.

Asistent přitom dostane do ruky tytéž nástroje, jaké má Agent v administraci, jen z druhé strany. Agent běží u nás a odvozuje si oprávnění z vaší role v týmu, kdežto přes MCP se připojuje program u vás a prokazuje se API klíčem, který mu vystavíte.

Nastavení najdete v Nastavení → API a MCP. Nahoře v kartě Externí přístup musí být zapnutý Server MCP; zapíná ho vlastník obchodu, poprvé s potvrzením odpovědnosti (postup je v článku API a MCP). Karta Připojení klienta pak ukazuje adresu serveru (končí na /api/mcp) a hotové nastavení pro Claude Code, Cursor, VS Code a jiného klienta. Místo VÁŠ_API_KLÍČ do něj doplníte svůj klíč; VS Code si klíč vyžádá sám a do souboru ho nepíše.

Vytvoření klíče a jeho oprávnění

Klíč pro asistenta vydává vlastník obchodu v Nastavení → API a MCP, v části Přístup a klíče:

V kartě API klíče klikněte na Vytvořit klíč.
Vyplňte Název klíče, ať je za půl roku poznat, komu patří (třeba „Claude na notebooku“).
V poli Kde klíč platí zvolte Jen server MCP, nebo REST API i server MCP, když má tentýž klíč sloužit i scénáři přes REST API.
Nastavte Platnost (doporučených je 90 dní) a Měsíční strop kreditů. Výchozí strop je 2 000 kreditů; nula asistentovi vypne všechno, co stojí kredity, a čtení i zápisy zdarma nechá.
Zaškrtejte oprávnění, nebo začněte Rychlou volbou. Oprávnění je čtyřiadvacet: dvanáct čtecích a dvanáct zápisových, a u každého je popiska, co konkrétně otevírá.
Klikněte na Vytvořit klíč a krok potvrďte heslem nebo kódem z e-mailu. Bez názvu, alespoň jednoho oprávnění a platného stropu vám to tlačítko nedovolí.

Klíč uvidíte jednou a naposledyPo vytvoření se ukáže v dialogu Klíč je vytvořený s tlačítkem na kopírování a s hotovým nastavením pro vašeho klienta, do kterého je klíč už doplněný. Ukládáme si jen jeho otisk, takže ho nepřečteme znovu ani my. Kdo si ho neuloží, musí založit nový.

Zaškrtávejte jen to, co má asistent opravdu dělat. Klíč jen se skladovými oprávněními neukáže objednávky ani osobní údaje zákazníků, a nástroje, na které oprávnění nemá, se mu vůbec nenabídnou. Nemůže si tedy říct ani o schopnost, o které neví, že existuje.

Co asistent uvidí

Co asistent uvidí, určují čtecí oprávnění klíče, která zaškrtáváte při vytvoření nebo přes Upravit klíč v Nastavení → API a MCP. Čtecích oprávnění je dvanáct a pokrývají objednávky, katalog (produkty, kategorie, dodavatele), sklad a nákup včetně feedů dodavatelů, doklady (jejich údaje, položky i stažení PDF a ISDOC), zákazníky se skupinami, recenzemi, zprávami z kontaktního formuláře, historií e-mailů a SMS (příjemce, předmět a stav, bez znění) a žádostmi podle GDPR, obsah stránek, blogu, sekcí a médií, marketing (slevy i s cílením, feedy, kampaně s výsledky rozesílky, segmenty a vyskakovací okna), nastavení obchodu i s dopravou, platbami, vzhledem, právními dokumenty, přesměrováním, měřicími kódy (bez tajemství) a stavem napojení na účetnictví, úkoly se seznamem členů týmu, statistiky, dokumentaci SHOPZI a hledání na webu.

Čtyři z nich stojí za rozmyšlenou navíc. Zákazníci obsahují osobní údaje, takže je dávejte jen tam, kde je bez nich odpověď nemožná. Statistiky naopak osobní údaje neobsahují vůbec, vrací jen souhrnná čísla za období: návštěvnost, SEO, hledání v obchodě, tržby a prodeje, i v porovnání s předchozím obdobím. Nákupní ceny, zisk ani marži přes klíč asistent nedostane nikdy. Dokumentace SHOPZI neotevírá data obchodu vůbec: je to náš veřejný návod, stejný pro všechny obchody, uživatelský i ten pro vývojáře, a asistent v něm umí hledat i číst celé kapitoly.

Hledání na webu je z celé té dvanáctky jediné, které sahá MIMO váš obchod, na veřejný internet, a jediné čtecí oprávnění, které něco stojí: každé hledání odečte kredity. Má proto vlastní zaškrtávátko (aby ho nikdo nedostal jako přílohu k něčemu jinému) a nad ním ještě druhý vypínač v Nastavení → AI, který je ve výchozím stavu vypnutý. Zapnout se musí obojí. Text, který asistent z webu přinese, nikdo neověřuje: bere se jako citace se zdrojem, ne jako údaj o vašem obchodě, a nikdy podle něj nic nezmění.

Přístupové údaje k platebním branám a další tajemství jsou v odpovědích maskované vždycky, ať má klíč oprávnění jakékoli.

Co smí změnit

Co asistent smí v obchodě změnit, určují zápisová oprávnění klíče, která zaškrtáváte ve skupině Zápis (jen server MCP) v Nastavení → API a MCP. Zápisové oprávnění dostala skoro vždycky jen ta oblast, jejíž změnu umíme spolehlivě vrátit: katalog, obsah, úkoly, sklad a zásobování, marketing, recenze a zákazníci, doprava, nastavení obchodu (včetně nastavení vyhledávání: synonyma, přesměrování, připnuté výsledky a fasety) a vzhled. Dvě zápisová oprávnění jsou přiznaná výjimka, protože jejich následek vzít zpět nejde: Objednávky (níž) a Předplatné, tedy navýšení tarifu, které strhne peníze z uložené karty (viz Navýšení tarifu z AI asistenta). Zákazníci zahrnují i rozhodnutí o velkoobchodní žádosti, o kterém zákazník dostane e-mail stejně jako z administrace. Katalog zahrnuje i odebrání variant, které vrátit nejde (asistent to řekne v otázce předem), a běžnou cenu existujících variant: asistent ji změní až po potvrzení, ve kterém vidíte cenu teď a nově, a změna se zapíše do třicetidenní historie cen stejně, jako když cenu změníte v administraci. Vrátit ji jde, vrácení je v historii další pohyb ceny. Sklad a zásobování zahrnují i feedy dodavatelů: odběry, cenová pravidla, frontu ke schválení a vlastní feed. Jednu věc z nich ale vrátit nejde: schválení objednávky u dodavatele ji dodavateli ODEŠLE e-mailem a ten podle ní pošle zboží zákazníkovi. Otázka to řekne předem.

Dvanácté zápisové oprávnění, Vrácení změn agenta, je protiváha k předchozím: bez něj asistent změní obchod, ale už ho nikdo nedokáže vrátit zpět. Zaškrtávejte ho vždy spolu s prvním zápisovým oprávněním.

Objednávky jsou přiznaná výjimkaOprávnění Objednávky (zápis) umí posunout stav objednávky, označit platbu a znovu poslat už vystavenou fakturu, a to všechno ODEŠLE zákazníkovi e-mail, který se stáhnout nedá. U objednávky placené kartou nebo na dobírku navíc označení platby vystaví daňový doklad, stejně jako když platbu potvrdíte v administraci. Vrácení takové změny nástroj odmítne a řekne proč, místo aby ho předstíral. Patří k němu i zásilky, vratky a zapsání zaplacení u faktury bez objednávky. Zrušit objednávku, vystavit doklad nebo dobropis, vrátit peníze ani rozhodnout reklamaci tím ale nejde.

Co ze systému jednou odejde, zpátky vzít nejde, a proto pro to zápisové oprávnění většinou vůbec neexistuje: rozeslaná kampaň, vystavený doklad, feed už stažený srovnávačem. U feedu je hranice uvnitř oblasti: nastavit ho (kanály, mapování kategorií, výjimky u položek) asistent umí, vygenerovat ho znovu ne. Stejně tak nemá žádné oprávnění nebezpečná zóna (reset nastavení, hromadné smazání produktů, pozastavení účtu). Schopnost, kterou nejde pojmenovat, nejde ani omylem udělit. Podrobný soupis je v článku Co Agent umí v obchodě změnit.

Co přepisuje, to se vás napřed zeptáAgent v administraci se před každou změnou zeptá naší vlastní kartou. Přes MCP se ptáme taky, jen jinak: nástroj, který něco PŘEPISUJE nebo maže, odpoví otázkou, váš klient ji ukáže vám, a teprve vaše potvrzení změnu spustí. Do té chvíle se v obchodě nezmění nic. Otázka se objeví jako dialog v okně vašeho klienta (v Claude Code třeba s volbou „Ano, provést“), ne jako zpráva v konverzaci: asistent ji sám nevidí, a proto mu po potvrzení výsledek řekne, že jste akci schválili, a u placené akce i kolik stála a kolik kreditů zbývá. Bez ptaní se provede jediná věc, a to založení úkolu na nástěnce: varování u všeho je varování u ničeho, a úkol nic nepřepíše ani nic nestojí. Nový článek nebo naskladnění se ptají taky, protože obojí mění obsah obchodu. Výjimkou je to, co stojí vaše kredity, tedy generování obrázků a videí, hledání na webu a hromadná AI úprava produktů: na to se ptáme taky, protože utracené kredity se nevrací, a otázka rovnou řekne, kolik to stojí a kolik vám zůstane. Otázka je podepsaná a svázaná s konkrétními hodnotami, takže se mezi ní a provedením nedá vyměnit, co se má stát. Klient, který se ve svém okně zeptat neumí, dostane místo otázky odkaz, přes který změnu schválí vlastník nebo manažer přímo v administraci (navýšení tarifu jen vlastník, a s druhým ověřením), a do té doby se neprovede nic; viz Schválení změn z AI asistenta. Vaší další pojistkou zůstává rozsah klíče a deník změn.

REST API zůstává jen ke čteníZápisová oprávnění platí pouze pro asistenta přes MCP. Přes běžné REST API na adresách /api/v1 se data jenom čtou, ať klíč zaškrtnuté má, nebo ne.

Bezpečnost a odvolání klíče

V kartě API klíče v Nastavení → API a MCP je u každého klíče jeho začátek (celý klíč nikde neuvidíte), stav Aktivní, Vyměněný, dobíhá, Vypršel nebo Odvolaný, kdy byl naposledy použit, kolik volání dnes přišlo a jaká má oprávnění.

Ikona Odvolat klíč ho zneplatní okamžitě a nevratně. Použijte ji vždy, když se klíč mohl dostat k někomu dalšímu, i kdyby jen omylem v chatu. Všechno, co klíč používalo, přestane fungovat ve stejnou vteřinu. Týká se to i odkazů ke stažení dokladů, které asistent přes ten klíč dostal: odkaz platí patnáct minut, ale jen dokud platí klíč, který si o něj řekl. Když klíč jen nahrazujete, použijte Vyměnit klíč: starý pak funguje ještě 24 hodin, než ho v klientovi vyměníte.

Pro každého asistenta i každý scénář raději samostatný klíč: pak se dá odvolat právě ten jeden, aniž byste vypnuli ostatní. Co který klíč dělá, ukazuje část Protokol volání.

Časté potíže

Asistent nevidí nástroj, který má podle vás mít. Klíči chybí odpovídající oprávnění. Vlastník obchodu ho doplní přes Upravit klíč; tajemství se tím nemění, takže klienta nemusíte přenastavovat.

„Přístupový klíč nemá oprávnění.“ Totéž z druhé strany: asistent nástroj zavolal, ale klíč na něj nedosáhne. Oprávnění se doplní stejně, přes Upravit klíč.

Asistent hlásí external_access_not_enabled. Server MCP je vypnutý. Zapněte ho v kartě Externí přístup.

Nástroj, který stojí kredity, odmítne kvůli stropu. Klíč vyčerpal měsíční strop kreditů. Strop změníte přes Upravit klíč, jinak se obnoví prvního dne dalšího měsíce. Strop nastavený na nulu znamená, že klíč utrácet nesmí vůbec, a nový měsíc na tom nic nezmění.

Asistent hlásí, že obchod není dostupný. Pozastavený nebo neaktivní obchod neodpovídá ani na čtení: server MCP i REST API vracejí 503 s větou, že obchod je momentálně nedostupný. Stav předplatného najdete v Nastavení → Předplatné.

Nedaří se připojit. Zkontrolujte, že je v nastavení celá adresa i s /api/mcp, že klíč je ve stavu Aktivní a že je zapnutý server MCP.

Technickou stránku téhož, tedy transport, potvrzovací kola a rejstřík nástrojů, popisuje článek MCP server v dokumentaci pro vývojáře; nastavení konkrétního klienta krok za krokem Připojení asistenta k obchodu.