Založení obchodu přes MCP

Nový obchod jde založit přímo z terminálu. Na adrese https://shopzi.cz/api/mcp běží server MCP bez klíče, který umí jen jedno: připravit koncept obchodu. Obchod z něj vznikne, až člověk v prohlížeči ověří e-mail, přijme podmínky a uloží platební kartu. Prvních 30 dní je zdarma a první platba přijde 31. den. Klíč k novému obchodu se pak ukáže jednou, v tom prohlížeči, a asistent se s ním připojí k serveru MCP obchodu na jeho vlastní adrese.

Připojení klienta

Server mluví revizí protokolu 2026-07-28: bez zahajovací výměny, bez sezení, jen POST. Hlavičku Authorization neposílejte, žádný klíč tu neexistuje.

claude mcp add --transport http shopzi-zalozeni https://shopzi.cz/api/mcp

Klient, který čte konfiguraci ze souboru, dostane jen adresu:

{
  "mcpServers": {
    "shopzi-zalozeni": { "url": "https://shopzi.cz/api/mcp" }
  }
}

Požadavek s hlavičkou Origin, tedy z webové stránky, server odmítne kódem 403 origin_not_allowed. Terminál ji neposílá; odmítnutí zastaví webovou stránku, která by server zkoušela volat z prohlížeče návštěvníka. GET i DELETE odmítne kódem 405 method_not_allowed s hlavičkou Allow: POST.

Nástroje

Parametry každého z nich vypisuje reference MCP bez klíče: tarify a založení obchodu.

Výpis nástrojů je pro všechny stejný a nese cacheScope: public s hodinovou platností, takže si ho klient smí pamatovat. Server hlásí listChanged: false. Hledání v dokumentaci tu jede jen fulltextem, bez sémantického vyhledávání.

Průběh

Asistent připraví koncept v terminálu, člověk ho v prohlížeči dokončí v pěti krocích (stránka je čísluje od „Krok 1 z 5“ do „Krok 5 z 5“) a nakonec se asistent připojí k hotovému obchodu.

1. Ceník a subdoména. Asistent zavolá shopzi_list_plans a shopzi_check_subdomain. Kontrola subdomény nikdy nejmenuje cizí obchod, řekne jen ano, nebo ne. Subdoména má 3 až 30 znaků: malá písmena bez diakritiky, číslice a pomlčky, bez pomlčky na začátku, na konci a bez dvou za sebou.
2. Koncept. shopzi_create_store s shop_name, subdomain, plan a interval založí koncept, který subdoménu drží 24 hodin. Klient, který deklaruje schopnost elicitation.url, dostane odkaz jako elicitaci URL a jeho SDK volání zopakuje samo; opakování vrátí tentýž koncept, nikdy druhý. Klient bez elicitace dostane výsledek rovnou. Výsledek i stav konceptu nesou vedle identifikátoru plan také plan_name, český název tarifu z ceníku (například Standard): pod ním tarif zná člověk, který obchod zakládá.
3. Odkaz a kód pro člověka. Asistent ukáže člověku draft_url a pairing_code (tvar ABCD-EFGH). Stránka ukáže, co se zakládá, kterým klientem, a varování „Pokračujte jen tehdy, pokud jste o založení požádali vy.“ Samotné otevření odkazu nic nezabere, takže náhled odkazu v chatu koncept nesebere.
4. Krok 1 z 5: párovací kód. Člověk zadá do pole Párovací kód z terminálu kód, který asistent vypsal, a klikne na Pokračovat v tomto prohlížeči. Stránka kód neukazuje: tím se ověří, že odkaz otevřel ten, kdo o obchod požádal. Koncept si tím nárokuje tenhle prohlížeč a jiný už v zakládání nepokračuje.
5. Krok 2 z 5: kdo bude obchod vlastnit. E-mail vlastníka a Heslo do administrace (aspoň 8 znaků), nebo Pokračovat přes Google či Pokračovat přes Apple. U e-mailu přijde šestimístný kód: platí 10 minut, zkusit ho jde pětkrát a poslat nejvýš třikrát za 15 minut, a že adresa už obchod vlastní, se dozvíte až po správném kódu, ne dřív. U účtu Google nebo Apple se na to, jestli už nějaký obchod vlastní, přijde hned, protože identitu ověřil poskytovatel; kód se v tom případě neposílá, pokud poskytovatel e-mail ověřil a nejde o skrytou adresu Applu.
6. Krok 3 z 5: vaše údaje. Jméno a příjmení a nepovinné IČO: údaje firmy se dohledají v ARES a předvyplní do průvodce, povinné je IČO až při spuštění obchodu.
7. Krok 4 z 5: podmínky. Souhlas s obchodními podmínkami SHOPZI, uzavření smlouvy o zpracování osobních údajů a potvrzení odpovědnosti za připojení klienta MCP, tlačítkem Souhlasím a pokračuji.
8. Krok 5 z 5: platební karta. Tlačítko Uložit kartu a spustit zkušební období otevře Stripe Checkout v češtině, jen pro kartu. Relace je nulová: karta se uloží, nic se z ní nestrhne a bez ní obchod nevznikne. Když se mezitím změnila cena tarifu, stránka ji ukáže dřív, než kartu zadáte.
9. Předání. Po uložení karty se obchod založí sám a stránka napíše, že je založený, běží zkušební období a z karty se zatím nic nestrhlo; obchod je zatím zavřený pro veřejnost. Tlačítko Zobrazit API klíč klíč vytvoří a ukáže jednou, spolu s hotovým nastavením pro Claude Code, Cursor, VS Code a jiného klienta. Tlačítko Otevřít administraci vás rovnou přihlásí: odkaz za ním platí pět minut a jen jednou, nové kliknutí vydá nový (jen první den po založení). Později se přihlásíte tak, jak jste se prokázali při zakládání: e-mailem a heslem, nebo účtem Google či Apple.
10. Server obchodu. Asistent se s klíčem připojí na https://<subdomena>.shopzi.cz/api/mcp a pokračuje nastavením obchodu. Jak na to, popisuje článek Připojení asistenta k obchodu.

Klíč a přístup po založení

Klíč z předání má všechna oprávnění, platí pro REST API i server MCP, vydrží 90 dní a měsíčně smí utratit nejvýš 2 000 kreditů. Server MCP má takový obchod zapnutý rovnou; REST API si vlastník zapíná sám.

Obojí najde vlastník v administraci nového obchodu v Nastavení → API a MCP, v části Přístup a klíče:

• v kartě Externí přístup je Server MCP zapnutý a REST API vypnuté; zapne ho přepínačem, poprvé s potvrzením odpovědnosti a s druhým ověřením;
• v kartě API klíče je klíč z předání s názvem, který končí „(založení obchodu)“, a s poznámkou „vydaný při založení obchodu z terminálu“. Upravit, vyměnit nebo odvolat se dá jako každý jiný;
• ztracený klíč se obnovit nedá, vlastník vydá nový tlačítkem Vytvořit klíč.

Stavy konceptu

shopzi_store_creation_status vrací jeden z těchto stavů:

Stav nikdy nevrací klíč, přihlašovací token ani údaje o vlastníkovi.

Limity

Server je bez klíče, takže stropy počítá podle sítě (u IPv6 podle celé sítě /64):

• tři živé koncepty z jedné sítě za 24 hodin, a nejvýš 20 pokusů o založení denně;
• shopzi_check_subdomain a shopzi_store_creation_status po 30 voláních za minutu;
• shopzi_docs 20 volání za minutu a 300 denně;
• ověřovací kódy e-mailem nejvýš 10 za hodinu.

Narazí-li strop volání, nástroj odmítne česky i s tím, za jak dlouho to zkusit znovu; u tří živých konceptů je potřeba některý dokončit, nebo počkat, až vyprší. Koncept platí 24 hodin a platba ve Stripe vyprší nejpozději s ním.

Časté potíže

Nástroj vrátí chybu. Kód chyby nese _meta výsledku pod klíčem cz.shopzi/errorCode:

Stránka píše, že založení pokračuje v jiném prohlížeči. Koncept už nárokoval jiný prohlížeč zadáním párovacího kódu. Dokončete ho tam, nebo požádejte asistenta o nový koncept.

Platba se nedokončila. Nic se nestrhlo. Stránka se vrátí na krok platby a platbu jde otevřít znovu, dokud koncept platí.

Karta uložená, ale obchod se nezakládá. Založení se opakuje samo, při každém doručení od Stripe i každých deset minut. Když nevyjde ani po pěti pokusech, stav se změní na needs_support, kupující dostane e-mail a náš tým obchod založí ručně, nebo předplatné zruší (ve zkušebním období se nic nestrhlo, takže není co vracet). Když založení narazí na střet, který opakování nevyřeší (subdoménu nebo e-mail vlastníka mezitím dostal jiný obchod), přejde stav na needs_support hned. Do té doby koncept subdoménu i e-mail dál drží, takže je mezitím nikdo jiný nezabere. Po zrušení předplatného se stav změní na expired a subdoména se uvolní.

Subdoménu mezitím dostal jiný obchod. Platba se neotevře. Asistent musí založit nový koncept s jinou subdoménou.