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č)
- Otevřete Customize a v něm Connectors.
- Klikněte na Add a zvolte Add custom connector.
- Vyplňte Name (jak se konektor bude jmenovat v seznamu, třeba Smable) a do Remote MCP server URL vložte adresu serveru.
- 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
- Zapněte režim pro vývojáře: Settings → Apps → Advanced settings → Developer mode (v některých verzích Settings → Connectors → Advanced settings).
- 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_idu 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_itemsvrá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_categoriesseř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_staffvrací 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_profitdá 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_pricenejdří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_availabilitypoložku skryje z pokladny, opět s potvrzením. - „Napočítal jsem 8 kg mouky, srovnej to ve skladu."
adjust_stocknastaví 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_unsoldvrá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. Volbamode: weakestmí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_elementsvyhledá 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_recipevypíš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_recipenastavuje 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_templatesvypíš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_templateskupinu 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_rolesnač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_employeepř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_helpprohledá 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ástrojsearch_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:
- 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á.
- 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).
- 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ástrojemget_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
- Otevřete Nastavení → Připojení AI asistenta.
- 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.
- V Nastavení → Připojení AI asistenta vytvořte přístup a poznamenejte si Client ID i Client secret — secret se zobrazí jen jednou.
- 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"
- 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čkejtedata.retry_aftersekund a zkuste znovu. - Odpověď s
isErrora 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
isErrora 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.