# Založení obchodu přes MCP

> Jak klient MCP bez klíče připraví nový obchod na shopzi.cz: nástroje, koncept, krok v prohlížeči, platba, předání klíče a co dělat, když se něco nepovede.

- Sekce: Pro vývojáře
- Stránka: https://shopzi.cz/dokumentace/vyvojari/zalozeni-obchodu-pres-mcp
- Ověřeno: 2026-10-20

---

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.

> **Tenhle server je jiný než server obchodu** Server na shopzi.cz nemá klíč a nesahá na žádný existující obchod. Server obchodu běží na doméně obchodu, chce API klíč a jeho nástroje popisuje článek MCP server.

## Připojení klienta [#pripojeni-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.

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

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

```json
{
  "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 [#nastroje]

| nástroj                        | co dělá                                                                                                         | co vrátí                                                                                                                              |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `shopzi_list_plans`            | ceník tarifů, které jde přes MCP založit                                                                        | ceny v haléřích přímo ze Stripe, limity tarifů, poznámku o DPH a o zkušebním období (30 dní zdarma, karta hned, první platba 31. den) |
| `shopzi_check_subdomain`       | ověří subdoménu                                                                                                 | `available`, důvod (`invalid_format`, `reserved`, `taken`) a volné návrhy                                                             |
| `shopzi_create_store`          | založí koncept, nic neúčtuje a nikomu nepíše                                                                    | `draft_url`, `pairing_code`, `status_token`, `expires_at`, cenu v haléřích a další kroky česky                                        |
| `shopzi_store_creation_status` | stav konceptu podle `status_token`                                                                              | stav, u hotového obchodu jeho adresu a adresu administrace                                                                            |
| `shopzi_docs`                  | hledá a čte obě dokumentace SHOPZI, uživatelskou i tuhle pro vývojáře; pole `docs` hledání zúží na jednu z nich | výsledky hledání, nebo článek či jednu jeho kapitolu                                                                                  |

Parametry každého z nich vypisuje reference
[MCP bez klíče: tarify a založení obchodu](/dokumentace/vyvojari/mcp-platforma).

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 [#prubeh]

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](/dokumentace/vyvojari/pripojeni-asistenta).

> **Klíč nikdy nepřijde do terminálu ani e-mailem** Asistent ho z nástroje stavu nedostane a e-mail o založení ho nenese. Ukáže se jen v prohlížeči, který koncept nárokoval, a znovunačtení stránky ho už nevrátí, protože v databázi je jen jeho otisk. Nový klíč vytvoříte v Nastavení → API a MCP.

## Klíč a přístup po založení [#klic-a-pristup-po-zalozeni]

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 [#stavy-konceptu]

`shopzi_store_creation_status` vrací jeden z těchto stavů:

| stav                  | co znamená                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| `waiting_for_browser` | koncept čeká na člověka v prohlížeči (párovací kód, e-mail, údaje, podmínky)                         |
| `waiting_for_payment` | stránka Stripe pro uložení karty je otevřená; relace je na nulu s `trial_end`, takže se nic neúčtuje |
| `paid_provisioning`   | karta uložená, obchod se zakládá                                                                     |
| `ready`               | obchod stojí, výsledek nese `shop_url` a `admin_url`                                                 |
| `needs_support`       | karta uložená, ale obchod se nepodařilo založit, řeší ho podpora                                     |
| `expired`             | koncept vypršel nebo byl zrušený a subdoménu už nedrží                                               |

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

## Limity [#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 [#caste-potize]

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

| kód                                                                 | příčina                                                      | co dělat                                                                       |
| ------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `draft_limit`                                                       | ze sítě běží tři nedokončené koncepty                        | dokončit některý z nich, nebo počkat, až vyprší                                |
| `subdomain_taken`, `subdomain_reserved`, `subdomain_invalid_format` | subdoména nejde použít                                       | vybrat jinou, `shopzi_check_subdomain` nabídne volné                           |
| `store_creation_disabled`                                           | zakládání přes MCP je dočasně vypnuté                        | zkusit později, nebo založit obchod na shopzi.cz                               |
| `plan_unavailable`, `plans_unavailable`                             | cenu se nepodařilo ověřit ve Stripe                          | zkusit za chvíli                                                               |
| `state_mismatch`, `invalid_state`                                   | opakované volání elicitace nesedí na první kolo              | zavolat nástroj znovu s původními hodnotami                                    |
| `invalid_input`                                                     | chybí nebo nesedí hodnota parametru, třeba `read` bez `slug` | opravit zadání podle věty v odmítnutí                                          |
| `rate_limited`                                                      | narazil strop podle sítě                                     | počkat, věta řekne jak dlouho                                                  |
| `not_found`                                                         | neznámý `status_token`                                       | použít token z výsledku `shopzi_create_store`                                  |
| `internal_error`                                                    | vnitřní chyba serveru                                        | zkusit za chvíli, nebo napsat na [podpora@shopzi.cz](mailto:podpora@shopzi.cz) |

**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.