Připojení asistenta k obchodu

Připojení asistenta je jedno políčko s adresou a jedno s klíčem. Tenhle článek je o tom, co dát do kterého a jak poznat, že to funguje, ještě než se na to začnete ptát v chatu.

Postup

Všechno, co asistent od obchodu potřebuje, nastaví vlastník obchodu v Nastavení → API a MCP, v části Přístup a klíče. Nastavení se otevře přes celou obrazovku a oddíl API a MCP najdete v levém sloupci ve skupině Technické.

1. Zapněte server MCP přepínačem u řádku Server MCP v kartě Externí přístup. Zapíná ho jen vlastník obchodu, poprvé s potvrzením odpovědnosti a pokaždé s druhým ověřením (heslo, nebo kód z e-mailu). Dokud je vypnutý, vrací server 403 external_access_not_enabled i na správný klíč.
2. Založte klíč v kartě API klíče tlačítkem Vytvořit klíč. V poli Kde klíč platí zvolte Jen server MCP nebo REST API i server MCP a zaškrtejte oprávnění, která má asistent mít; rychlé volby Objednávky a sklad a Obsah a marketing nastaví rovnou server MCP. Měsíční strop kreditů určuje, kolik smí asistent tímhle klíčem za měsíc utratit za placené akce (výchozí 2 000). Viz Autentizace a oprávnění.
3. Zkopírujte nastavení z dialogu Klíč je vytvořený, který nový klíč ukáže (část Připojení asistenta přes MCP), nebo později z karty Připojení klienta, kde místo klíče stojí VÁŠ_API_KLÍČ. V obou přepínáte mezi Claude Code, Cursor, VS Code a Jiný klient a tlačítko Kopírovat vezme celé nastavení. V dialogu je klíč už doplněný, kromě nastavení pro VS Code: tam se klíč do souboru nepíše a VS Code se na něj zeptá při spuštění serveru. Adresa vašeho obchodu je v obou.
4. Vložte ho do klienta a doplňte klíč, pokud v nastavení ještě chybí.
5. Ověřte si to voláním tools/list (níž), ne prvním dotazem v chatu. Chyba v konfiguraci se z odpovědi asistenta pozná mizerně.

Tvar nastavení

Většina klientů čte konfiguraci v tomhle tvaru. Adresa je doména vašeho obchodu s cestou /api/mcp, autorizace jde jako běžná hlavička. Jméno serveru skládá administrace z shopzi- a subdomény obchodu, aby šlo mít připojených víc obchodů naráz.

{
  "mcpServers": {
    "shopzi-muj-eshop": {
      "url": "https://muj-eshop.cz/api/mcp",
      "headers": {
        "Authorization": "Bearer VÁŠ_API_KLÍČ"
      }
    }
  }
}

Klienta, který umí jen spouštět místní proces (command a args), propojte přes libovolný můstek stdio na HTTP. Server sám žádný balíček ke spuštění nevydává: je to HTTP endpoint, ne program.

Ověření z příkazové řádky

První volání může být rovnou tools/list, žádná zahajovací výměna se nečeká. Odpověď má obsahovat seznam nástrojů odpovídající oprávněním klíče.

curl -s https://muj-eshop.cz/api/mcp \
  -H "Authorization: Bearer $SHOPZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Vedle nástrojů server nabízí i prompts/list, tedy hotové otázky, které se ve většině klientů objeví jako lomítkové příkazy. Filtrují se podle rozsahu klíče stejně jako nástroje.

Co je server zač, řekne server/discover: vrátí podporované revize protokolu, schopnosti serveru a krátký úvodní text pro model. Klientovi, který se hlásí revizí 2026-07-28, nese _meta každé odpovědi i jméno a verzi serveru pod klíčem io.modelcontextprotocol/serverInfo, protože bez zahajovací výměny není kde jinde se představit.

Výpisy (tools/list, prompts/list, server/discover) nesou ttlMs a cacheScope s hodnotou private: smíte si je minutu pamatovat, ale jen pro ten klíč, kterým jste se ověřili, protože obsah se podle klíče liší. Oznámení o změně seznamu nástrojů od nás nečekejte, server poctivě hlásí listChanged: false.

Napovídání hodnot

U vybraných argumentů umí server completion/complete, tedy nabídku skutečných hodnot z vašeho obchodu: klient, který ji podporuje, ukáže při psaní příkazu rovnou existující produkty, kategorie nebo objednávky. Nabízí se popisek, ne identifikátor (název produktu, číslo objednávky), protože rozbalovací seznam osmi náhodných UUID je sice přesnější, ale lidsky nepoužitelný. Hledá se od dvou znaků a vrátí se nejvýš deset návrhů; každé napovídání se počítá do stropu volání klíče a nad strop vrátí prázdnou nabídku. Klient, který completion/complete neumí, o nic nepřijde: argument se prostě vypíše ručně.

Doklady se vracejí jako odkaz, ne jako příloha

Detail dokladu (shopzi_list_documents v režimu detail) nese vedle textu i bloky resource_link s adresou PDF a ISDOC. Adresa míří na doménu vašeho obchodu a je podepsaná a platná patnáct minut. Tiskovou dávku štítků Zásilkovny ani štítek jedné zásilky takhle nepodáváme: každé otevření štítku je volání dopravce, a proto zůstávají jen v administraci.

Časté potíže

Nepřipojí se a v protokolu je 405. Klient volá GET nebo DELETE. Transport je od revize 2026-07-28 jen POST; klient, který se pokouší otevřít SSE stream nebo ukončit sezení, mluví starší revizí protokolu. Samotná starší revize problém není: požadavek se zahajovací výměnou server obslouží bezstavově.

Vrací 401. Hlavička s klíčem chybí, nebo hodnota nezačíná Bearer shopzi_sk_ (u hlavičky x-api-key rovnou shopzi_sk_), a pak přijde missing_api_key. Nebo klíč není platný: je odvolaný, vypršel, případně patří jinému obchodu (invalid_api_key). Klíč pro server MCP ověřte voláním tools/list výš; /api/v1/ping pomůže jen u klíče, který platí i pro REST API, protože ping patří k REST API.

Vrací 403. Kód v těle říká co: external_access_not_enabled (server MCP není zapnutý), plan_required (obchod je na tarifu Free, ve zkušebním období bez uložené karty, nebo má zrušené předplatné), external_access_suspended nebo external_access_disabled (pozastavení od SHOPZI), key_surface_mismatch (klíč platí jen pro REST API) a origin_not_allowed (požadavek přišel z webové stránky s hlavičkou Origin). Všechny popisuje článek Chybové odpovědi.

Připojí se, ale nabízí jen zakládání obchodu. Adresa míří na shopzi.cz, kde běží server bez klíče, který umí jen ceník tarifů, kontrolu subdomény a koncept nového obchodu. Server vašeho obchodu je na jeho vlastní doméně.

Vrací 503 „Tento obchod je momentálně nedostupný.“ Obchod je pozastavený nebo neaktivní, nebo na té doméně žádný obchod neběží. Odmítá ho vrstva před API, takže odpověď nemá kód chyby.

Nástroj odmítne s approval_required. Klient nehlásí schopnost elicitation, takže mu server nemá jak položit otázku, kterou před takovou akcí položit musí. Místo provedení proto vrátí odkaz na stránku schválení v _meta["cz.shopzi/approvalUrl"]: člověk ji v administraci schválí (vlastník nebo manažer, u navýšení tarifu jen vlastník s druhým ověřením) a vy zavoláte nástroj znovu se stejnými argumenty. Dokud se čeká, přijde approval_pending. Týká se to všeho, co přepisuje nebo maže, co sahá na veřejný internet, co utrácí kredity obchodu a co strhává peníze z karty. Bez otázky dál funguje běžné čtení, založení úkolu, spočítání nabídky navýšení tarifu (upgrade bez quote) a odkaz na nákup kreditů.

Nástroj skončí chybou conflict o překročeném limitu. Volání nástrojů se počítají klíči v hodinovém i denním okně podle tarifu, a vedle toho má obchod vlastní strop AI generování, do kterého se počítá i práce Agenta v administraci. Věta v odmítnutí říká, který ze dvou stropů narazil. Je to dočasný stav, takže zkuste to s odstupem, a když narazil strop klíče a ne obchodu, hledejte rozběhnutou integraci. Čísla podle tarifu jsou v článku Chybové odpovědi.

Nástroj skončí chybou credit_cap_exceeded. Placená akce by překročila měsíční strop kreditů klíče. Nestrhlo se nic; strop se obnoví prvního dne dalšího měsíce, nebo ho vlastník obchodu zvýší v Nastavení → API a MCP ikonou Upravit klíč v poli Měsíční strop kreditů. Strop nula utrácení klíči vypíná úplně.

Výpis objednávek vrátí nulu, přestože objednávky v obchodě jsou. Výpis žádný skrytý filtr nemá, takže nulu způsobil filtr, který asistent poslal, nejčastěji obecné slovo z otázky („web“, „administrace“) v poli search, které hledá jen v čísle objednávky, e-mailu a jménu na faktuře. Prázdná odpověď shopzi_search_orders proto nese applied_filters (co se opravdu filtrovalo), total_without_filters (kolik objednávek má obchod bez filtrů) a note s českou větou, co dál. Neprázdná odpověď tahle pole nemá.

Nástroj skončí chybou invalid_input o klíči idempotence. Klíč, který jste poslali, už patří jiné změně. Stejný klíč smí nést jen opakování téhož volání; pro novou změnu pošlete nový.

Dávka požadavků vrátí 400. Pole několika požadavků v jednom těle server přijme, ale ne tehdy, když je v něm completion/complete nebo subscriptions/listen: ty posílejte jednotlivě. Odběry server nevede vůbec, takže subscriptions/listen odmítne i samostatně.

Než to pustíte naostro

• Vlastní klíč pro každého asistenta i každý stroj. Pak jde odvolat právě ten jeden.
• Jen ta oprávnění, která asistent opravdu potřebuje. Zákaznická data dávejte jen tam, kde je bez nich odpověď nemožná.
• Rozumný strop kreditů. Klíč, který nemá co generovat ani hledat na webu, může mít strop nula.
• Text z internetu není údaj o obchodě. Co asistent přinese nástrojem na hledání, je citace se zdrojem, ne fakt o vašich datech, a nikdy podle toho nic neměňte automaticky.
• Klíč nepatří do promptu ani do chatu. Patří do konfigurace klienta, odkud ho model nevidí.

Obchodnická verze téhož postupu, tedy bez příkazové řádky, je v článku Připojení AI asistenta (MCP). Co umí Agent přímo v administraci, popisuje článek Agent. Jak asistent založí úplně nový obchod, i s předáním klíče, popisuje článek Založení obchodu přes MCP.