# Připojení asistenta k obchodu > Nastavení klienta MCP krok za krokem, ověření na příkazové řádce, co dělat s nástrojem, který se nenabídne, a jak z asistenta neudělat díru do dat. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/pripojeni-asistenta - Ověřeno: 2026-10-20 --- 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 [#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í](/dokumentace/vyvojari/autentizace-a-opravneni). 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ě. > **Obchod ještě nemáte?** Asistent ho umí připravit sám přes server MCP bez klíče na shopzi.cz: založí koncept, vy v prohlížeči ověříte e-mail a uložíte platební kartu (prvních 30 dní je zdarma), a klíč s hotovým nastavením pro Claude Code, Cursor, VS Code a jiného klienta se ukáže jednou na konci. Postup je v článku Založení obchodu přes MCP. ## Tvar nastavení [#tvar-nastaveni] 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. ```json { "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 [#overeni-z-prikazove-radky] 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. ```bash 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":{}}' ``` > **Kratší seznam, než jste čekali, znamená užší klíč** Nástroje se filtrují podle oprávnění klíče, takže v odpovědi je jen to, na co klíč dosáhne. Klíč bez jediného oprávnění vydat nejde, formulář ho nepustí. Oprávnění vydanému klíči doplní vlastník obchodu v Nastavení → API a MCP ikonou Upravit klíč; tajemství se tím nemění, takže klienta nemusíte přenastavovat. Klient si seznam smí minutu pamatovat, nový nástroj se proto může objevit až s minutovým zpožděním. 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 [#napovidani-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 [#doklady-se-vraceji-jako-odkaz-ne-jako-priloha] 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. > **Odkaz si uložte jako soubor, ne jako adresu** Krátká platnost je záměr: podpis jen přenáší oprávnění, které už má váš klíč, na adresu otevíratelnou bez našich cookies. Odkaz proto nemá smysl ukládat do databáze ani posílat dál. Stáhněte si soubor hned a uchovávejte ten; za čtvrt hodiny vrátí tatáž adresa 403, a dřív ho zneplatní i odvolání klíče nebo vypnutí serveru MCP. ## Časté potíže [#caste-potize] **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](/dokumentace/vyvojari/chybove-odpovedi). **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](/dokumentace/vyvojari/chybove-odpovedi). **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 [#nez-to-pustite-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)](/dokumentace/nastaveni/mcp-pripojeni-asistenta). Co umí Agent přímo v administraci, popisuje článek [Agent](/dokumentace/zaciname/agent). Jak asistent založí úplně nový obchod, i s předáním klíče, popisuje článek [Založení obchodu přes MCP](/dokumentace/vyvojari/zalozeni-obchodu-pres-mcp).