MCP server — připojení AI klienta k Smable API

Produkt: API · Aktualizováno: 2026-11-15

Pomocí MCP serveru (Model Context Protocol) propojíte svého AI asistenta — Claude, ChatGPT — přímo s daty své provozovny ve Smable. Asistent pak odpovídá z živých prodejních dat: kolik jste čeho prodali, které kategorie táhnou, jak si vedou zaměstnanci. S výslovným oprávněním umí i měnit ceny nebo stav skladu, vždy až po vašem potvrzení.

  • Adresa serveru: https://mcp.smable.cz/mcp
  • Přístup: vždy jen k provozovnám, které jste na souhlasné obrazovce vybrali
  • Cena: placená služba, shrnutí viz sekce Kolik to stojí

Připojení podle klienta

Adresa serveru je vždy stejná — https://mcp.smable.cz/mcp — liší se jen místo, kam ji ve svém klientovi vložíte. Hesla ani klíče se nikam nekopírují.

Claude (claude.ai i aplikace pro počítač)

  1. Otevřete Customize a v něm Connectors.
  2. Klikněte na Add a zvolte Add custom connector.
  3. Vyplňte Name (jak se konektor bude jmenovat v seznamu, třeba Smable) a do Remote MCP server URL vložte adresu serveru.
  4. Potvrďte tlačítkem Continue. Konektor se objeví v seznamu; připojíte ho tlačítkem Connect, které spustí přihlášení do Smable.

Ve firemním účtu (Team, Enterprise) přidává konektor vlastník účtu v Organization settings → Connectors. Ostatní členové ho pak najdou v Customize → Connectors a kliknou na Connect. V konverzaci se konektor zapíná tlačítkem + pod polem pro psaní, v sekci Connectors. Vlastní konektory fungují na tarifech Free, Pro, Max, Team i Enterprise.

ChatGPT

  1. Zapněte režim pro vývojáře: Settings → Apps → Advanced settings → Developer mode (v některých verzích Settings → Connectors → Advanced settings).
  2. Přidejte vlastní konektor a vložte adresu serveru.

Funguje ve webové verzi ChatGPT na tarifech Plus, Pro, Business, Enterprise a Edu. Ve firemním účtu zapíná režim pro vývojáře jeho administrátor. ChatGPT si navíc nechá potvrdit každou akci, která mění data.

Claude Code

Stačí jeden příkaz v terminálu:

claude mcp add --transport http smable https://mcp.smable.cz/mcp

Klient, který vlastní server neumí

V aplikaci Smable otevřete Nastavení → Připojení AI asistenta, vytvořte přístup a vložte do klienta Client ID a Client secret ručně. Secret se zobrazí jen jednou.

Názvy položek se u každého klienta trochu liší a výrobci je průběžně mění — hledejte v jeho nastavení položku Konektory nebo MCP. Předpokladem je klient, který umí připojit vlastní MCP server; u některých je to vázané na vyšší tarif nebo na zapnutí režimu pro vývojáře.

Endpoint přijímá jen POST. GET slouží ve Streamable HTTP transportu k volitelnému SSE streamu, který tenhle server nenabízí, a vrací proto 405 s hlavičkou Allow: POST — otevření adresy v prohlížeči skončí právě touhle hláškou.

Co uvidíte na souhlasné obrazovce

Po vložení adresy otevře klient prohlížeč, vy se přihlásíte do Smable a objeví se souhlasná obrazovka.

  • Nadpis „<jméno klienta> chce přístup k vašim datům ve Smable".
  • Výběr provozoven zaškrtávátky. Volba I provozovny, které přidáte později znamená celý účet.
  • Výběr oprávnění ve dvou skupinách:
    • Čtení — prodejní reporty, ceník, sklad. Změny okruhů pokladen a stolů asistent jen navrhne a majitel je schvaluje v aplikaci.
    • Změny — asistent smí měnit ceny a položky, sklad, receptury, zakládat zákazníky a zaměstnance a provádět další zápisy. Vždy je nejdřív navrhne a provede až po vašem potvrzení v chatu.
  • Volba Nahradit dřívější připojení — zobrazí se, jen když už tohoto asistenta připojeného máte. Je předem zaškrtnutá a dřívější připojení téhož asistenta se odpojí; odškrtnutím ho ponecháte.
  • Rámeček Cena za přístup k datům a povinný souhlas s cenou.
  • Řádek Přihlášeni jako <váš e-mail> a odkaz Přihlásit jako někdo jiný — ten použijte, když jste přihlášeni pod účtem, který k dané provozovně nepatří.
  • Tlačítka Povolit přístup a Zamítnout, pod nimi připomínka, že souhlas jde kdykoli zrušit v Nastavení → Připojení AI asistenta.

Jednotlivá oprávnění uvnitř skupiny odškrtnout nejdou, zaškrtává se celá skupina. Čtení je předem zaškrtnuté, ale jde odškrtnout. Změny jsou volitelné a předem zaškrtnuté nejsou. Aby šlo přístup povolit, musí být zaškrtnutá aspoň jedna skupina. Cena změn už čtení obsahuje. Po povolení se klient sám propojí. Přístupový token platí 15 minut a klient si ho po dobu 30 dní obnovuje sám, takže připojení nemusíte opakovat.

Víc provozoven jedním souhlasem

Jeden souhlas může pokrýt víc provozoven. Pro takový souhlas se v seznamu nástrojů objeví navíc:

  • nástroj list_sales_channels — vrátí provozovny, které smí připojení použít (ID a název);
  • nepovinný parametr sales_channel_id u každého dalšího nástroje. Bez něj běží nástroj nad výchozí provozovnou souhlasu.

Asistent si tedy nejdřív načte seznam provozoven a jejich ID pak předává ostatním nástrojům. Provozovnu, která v souhlasu není, server odmítne. U souhlasu s jedinou provozovnou nástroj list_sales_channels ani parametr sales_channel_id v seznamu nejsou.

Kdo může připojení povolit a odpojit

Připojení povolit i odvolat smí jen majitel účtu nebo zaměstnanec s rolí, která má přístup do backoffice. Zaměstnanec bez takové role uvidí hlášku, že se má obrátit na majitele.

Limity volání

Volání nástrojů od AI klientů třetích stran jsou omezena na 60 za minutu na jedno připojení. Je to jeden společný limit pro celé připojení, i když pokrývá víc provozoven, a po provozovnách se nedělí. Na jednu provozovnu platí navíc 5000 volání za den ze všech připojení dohromady. Nástroj search_help se do limitu nepočítá.

Po překročení limitu server odpoví HTTP 429 s hlavičkou Retry-After a chybou JSON-RPC -32029; pole data.retry_after udává počet sekund, které je potřeba počkat. Asistent dostane dočasné odmítnutí a zkusí to znovu.

Kolik to stojí

  • AI asistent – čtení 190 Kč a AI asistent – změny 390 Kč za provozovnu a měsíc, bez DPH. Čtení je v ceně změn.
  • Každá další provozovna stejného majitele stojí polovinu: 95 Kč, respektive 195 Kč.
  • Účtuje se zpětně spolu s licencí pokladny, jen za měsíce, ve kterých asistent provozovnu použil. Provozovna s 10 a méně účtenkami za měsíc se neúčtuje.
  • Prvních 30 dní od prvního odsouhlasení ceny v účtu je zdarma. Možné je roční předplatné: zaplatíte 10 měsíců za 12.
  • Předplatné Claude nebo ChatGPT se platí jeho poskytovateli, ne Smable.

Odhad měsíční ceny aktuální provozovny uvidíte v Nastavení → Připojení AI asistenta nad seznamem připojených asistentů. Připojení vytvořená před zavedením ceny fungují ještě po přechodnou dobu, jejíž konec vám oznámíme e-mailem. Aby asistent fungoval dál, připojte ho znovu a odsouhlaste cenu ještě před tímto dnem.

Na co se můžete ptát

Ptejte se běžnou řečí, asistent si sám vybere nástroj. Ukázky odpovědí jsou obecné — konkrétní čísla vždy přijdou z vašich dat.

Prodeje a tržby

  • „Kolik jsme prodali za posledních 30 dní?" Přes report_items vrátí tabulku položek s počtem kusů a tržbou za období.
  • „Které kategorie měly minulý měsíc nejvyšší tržbu?" report_categories seřadí kategorie podle tržby za zvolené období.
  • „Co se nám prodává nejhůř?" Tentýž položkový report, jen obráceně — asistent výsledek seřadí od nejmenšího prodeje.
  • „Kolik účtenek vydala Jana minulý týden a kolik dostala na spropitném?" report_staff vrací počet účtenek, tržbu a spropitné po jednotlivých zaměstnancích.
  • „Jak vypadal vývoj tržeb den po dni za poslední dva týdny?" report_profit dá denní řadu tržeb a nákladů.
  • „Porovnej mi červen a červenec." Asistent zavolá report dvakrát za různá období a rozdíl dopočítá sám.

Ceník a sklad

  • „Zvedni cenu černé kávy na 65 Kč." set_item_price nejdřív ukáže náhled „ze staré na novou cenu"; teprve po vašem potvrzení cenu změní. Vyžaduje oprávnění k úpravě položek.
  • „Vypni na pokladně sezónní limonádu, došla nám." set_item_availability položku skryje z pokladny, opět s potvrzením.
  • „Napočítal jsem 8 kg mouky, srovnej to ve skladu." adjust_stock nastaví absolutní stav suroviny — je to inventurní oprava, ne příjem zboží.
  • „Které položky se za poslední tři měsíce neprodaly ani jednou?" report_unsold vrátí souhrn za celý ceník — kolik položek do něj spadlo a u kolika je nula — a k tomu seznam s párovacími kódy. Volba mode: weakest místo toho seřadí ceník od nejslabších. Položky založené až během období se nezapočítávají, novinka není ležák.

Suroviny, receptury a modifikátory

  • „Kolik máme na skladě slaniny a v čem se počítá?" list_elements vyhledá surovinu podle názvu a vrátí označení, měrnou jednotku a stav skladu. Nákupní ceny nevrací.
  • „Z čeho se skládá burger a jaký je postup přípravy?" get_recipe vypíše recepturu položky včetně spotřeby jednotlivých surovin a uloženého postupu.
  • „Přidej do receptury na burger ještě plátek sýra." set_recipe nastavuje celou recepturu najednou, takže si asistent nejdřív načte stávající složení, připojí novou surovinu a předloží náhled celé nové receptury k potvrzení.
  • „Jaké máme modifikátory u jídel?" list_modifier_templates vypíše skupiny voleb i s příplatky u jednotlivých voleb.
  • „Založ skupinu Velikost s volbami malá za 0 a velká za 20 Kč." create_modifier_template skupinu vytvoří. Přiřazení ke konkrétním položkám se dělá v BackOffice.

Zaměstnanci

  • „Vypiš mi dostupné role pro zaměstnance včetně toho, co smí dělat." list_employee_roles načte role z katalogu a vypíše je i s popisem, co která role smí, a označí ty, které vidí do BackOffice.
  • „Založ nového číšníka Jana Nováka s maximální slevou 10 %." create_employee připraví náhled se zadanými údaji i s popisem role a zaměstnance vytvoří až po potvrzení. Oprávnění rozbalí server podle role; bez oprávnění k zakládání zaměstnanců nástroj odmítne.

Nápověda a nastavení

  • „Jak ve Smable nastavím tiskárnu účtenek?" search_help prohledá nápovědu Smable a shrne postup i s odkazem na článek.
  • „Jak se dělá uzávěrka pokladny?" Totéž — asistent odpoví z nápovědy, ne z vašich dat.

Zakládání zaměstnanců je samostatné oprávnění (public:employees.write). Skupina Změny na souhlasné obrazovce ho obsahuje; ručně vytvořený klient s oprávněním jen k úpravě položek zaměstnance zakládat nesmí.

Marže a nákupní ceny: asistentům třetích stran se nikdy neposílají. Připojený AI klient dostane počty kusů a tržby, ale ne nákupní ceny, náklady ani marži.

Dvě adresy: data a nápověda

Smable vystavuje dva MCP servery. Liší se tím, co nabízejí a jestli po vás chtějí přihlášení.

  • https://mcp.smable.cz/mcp — data vaší provozovny. Vyžaduje přihlášení vždy. Nepřihlášenému klientovi odpoví chybou 401, čímž mu dá pokyn, aby přihlášení spustil.
  • https://mcp.smable.cz/public/mcp — jen vyhledávání v nápovědě Smable, bez přihlášení, pro kohokoli. Nabízí jediný nástroj search_help. Když na téhle adrese zavoláte nástroj na prodejní data, server ho odmítne a odkáže vás na adresu s přihlášením. Případný token tady server ignoruje — data provozovny přes veřejnou adresu získat nelze.

Rozdělení není zbytečná komplikace: AI klienti spouštějí přihlášení až ve chvíli, kdy dostanou odpověď 401. Kdyby adresa s daty odpovídala i nepřihlášenému klientovi, považoval by se za připojený a o přihlášení by vás nikdy nepožádal.

Dostupné nástroje

Čtecí

Období se zadává ve formátu YYYY-MM-DD, nejvýše 366 dní. U souhlasu s víc provozovnami přijímá každý nástroj navíc nepovinný sales_channel_id (viz Víc provozoven jedním souhlasem).

Nástroj Co vrací Parametry
report_items prodeje po položkách — počet kusů a tržba date_from, date_to, volitelně item_id
report_categories prodeje po kategoriích date_from, date_to
report_staff prodeje po zaměstnancích — účtenky, tržba, spropitné date_from, date_to
report_profit tržba po dnech date_from, date_to
search_help články nápovědy k dotazu query, volitelně limit (1–20, výchozí 5)
list_elements suroviny podle názvu — označení, jednotka, stav skladu (bez nákupních cen) volitelně search, limit (1–50, výchozí 20)
get_recipe recepturu položky — suroviny, množství, postup item_id
list_modifier_templates skupiny voleb i s příplatky volitelně limit (1–50, výchozí 20)
list_employee_roles role zaměstnanců i s popisem, co role smí —
list_register_categories okruhy pokladen, pokladny, které podle nich jedou, a všechna nastavení s českým názvem a hodnotou volitelně register_category_id
list_tables sekce, plány mapy stolů a stoly s počtem míst, tvarem, rozměry a pozicí středu na plánu volitelně include_inactive
get_change_request stav požadavků ke schválení, které klient poslal majiteli volitelně change_request_id (bez něj posledních 10)
list_sales_channels provozovny, které smí připojení použít — ID a název; jen u souhlasu s víc provozovnami —
report_unsold ležáky — co se za období neprodalo, nebo žebříček nejslabších položek (souhrn za celý ceník + omezený výpis) date_from, date_to, volitelně mode (unsold / weakest), category_id, limit (1–1000, výchozí 100)

Nákupní ceny, hrubý zisk ani marži připojený asistent nedostane — ta čísla zůstávají jen v aplikaci Smable. Prodejní ceny položek se přes MCP zatím číst nedají, asistent je umí jen měnit (viz níže).

Zápisové

Nástroj Co dělá Pojistka
set_item_price nastaví prodejní cenu položky cena nejvýše 10 000 000
set_item_availability zapne/vypne položku na pokladně —
rename_item přejmenuje položku název max 255 znaků
create_customer založí zákazníka e-mail se ověřuje formátem
adjust_stock nastaví absolutní stav suroviny (inventura) množství nejvýše 10 000 000
set_recipe nastaví celou recepturu položky (nahrazuje stávající) nejvýše 100 surovin, množství musí být kladné
create_modifier_template založí skupinu voleb s příplatky nejvýše 50 voleb, příplatek nesmí být záporný
import_items hromadně založí položky (jen zakládá, duplicity nehlídá) nejvýše 100 položek najednou
create_employee založí zaměstnance a přidělí mu roli PIN 4–20 číslic, sleva 0–100 %, oprávnění rozbaluje server
update_register_category změní název nebo nastavení okruhu pokladen (např. default_screen: 0 Kalkulačka, 1 Rychlý prodej, 2 Knihovna; tables; employees) neznámý klíč je chyba, sklad okruhu se nemění; schvaluje majitel
save_tables založí nebo upraví stoly včetně sekcí a plánů zadaných jménem nejvýše 100 stolů, tvar jen circle / rectangle, sekce a plán musí patřit provozovně; schvaluje majitel

Změny dat a potvrzení

Zápisové nástroje mají tyto pojistky:

  1. Náhled napřed. První volání nic nezmění — vrátí jen srovnání současné a nové hodnoty. Teprve druhé volání s potvrzením změnu provede. Asistent se vás tedy vždy nejdřív zeptá.
  2. Vlastní oprávnění. Každý přímý zápis vyžaduje samostatné oprávnění ze skupiny Změny na souhlasné obrazovce. Bez něj asistent změnu neprovede. Výjimkou jsou návrhy změn okruhů pokladen a stolů — ty patří do skupiny Čtení a provedou se až po schválení majitelem (bod 3).
  3. Schválení majitelem. Změny okruhů pokladen a stolů (update_register_category, save_tables) se po potvrzení neprovedou, ale vznikne požadavek, který musí schválit majitel v administraci Smable (Nastavení → Připojení AI asistenta, sekce Ke schválení). Asistent stav ověří nástrojem get_change_request. Neschválené požadavky po sedmi dnech vyprší. Návrhy změn okruhů a stolů (public:registers.write, public:tables.write) patří do skupiny Čtení — asistent je jen navrhuje a provede je až schválení majitele. Klienti připojení dříve je obdrží až po opětovném udělení souhlasu.

Každý zápis se zapisuje do auditní stopy provozovny. Provozovna se navíc vždy kontroluje proti souhlasu — asistent může zadat jen provozovnu, kterou jste mu povolili, do cizích dat se zapsat nedá.

Odvolání přístupu

  1. Otevřete Nastavení → Připojení AI asistenta.
  2. V sekci Připojení asistenti klikněte u daného asistenta na Odvolat.

Asistent ztratí přístup nejpozději do 15 minut — tak dlouho může platit jeho poslední vydaný token. Nový už si nevymění. Od dalšího měsíce se provozovna neúčtuje, pokud ji nekryje jiné připojení.

Připojení pro vlastní skripty

Pro vlastní automatizace se hodí přímé server-to-server připojení bez souhlasové obrazovky.

  1. V Nastavení → Připojení AI asistenta vytvořte přístup a poznamenejte si Client ID i Client secret — secret se zobrazí jen jednou.
  2. Vyměňte je za token:
curl -X POST https://api-v3.smable.cz/v3/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials"
  1. Token přikládejte ke každému volání:
curl -X POST https://mcp.smable.cz/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"report_items",
                 "arguments":{"date_from":"2026-07-01","date_to":"2026-07-31"}}}'

Technické parametry: JSON-RPC 2.0 přes HTTP (MCP Streamable HTTP v JSON-response režimu), bez SSE streamování a bez dávkových požadavků. Podporované verze protokolu: 2025-06-18 (výchozí), 2025-03-26, 2024-11-05. Handshake initialize vrací i pole instructions, které si AI klient načte sám.

Když něco nefunguje

  • 401 — chybí nebo je neplatný token. U připojeného asistenta zkuste připojení obnovit; token po 30 dnech bez použití vyprší.
  • Chyba -32002 — token nemá přiřazenou aktivní provozovnu.
  • Chyba -32003 — token nemá oprávnění číst reporty. Typicky jde o token pokladny, který k MCP určený není.
  • Chyba -32004 — asistent zkusil zápis bez oprávnění, které jste mu nepovolili.
  • HTTP 429 a chyba -32029 — překročený limit volání. Počkejte data.retry_after sekund a zkuste znovu.
  • Odpověď s isError a výzvou „Připojení je potřeba obnovit a odsouhlasit cenu" — dřívější připojení, které po skončení přechodného období (termín oznámíme e-mailem) musí být odpojeno a znovu připojeno s přijetím ceny.
  • Odpověď s isError a výzvou „Pro tento přístup zatím nebyla odsouhlasena cena" — ručně vytvořený přístup (Client ID a Client secret), u kterého po skončení přechodného období (termín oznámíme e-mailem) chybí odsouhlasená cena. Odpojení a nové připojení v asistentovi nepomůže. V aplikaci Smable otevřete Nastavení → Připojení AI asistenta a u přístupu klikněte na Odsouhlasit cenu. Client ID ani Client secret se nemění, v asistentovi nic měnit nemusíte.
  • Odpověď s isError — neplatné vstupy: období delší než 366 dní, záporná cena, prázdný název.