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

Produkt: API · Aktualizováno: 2026-08-25

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 té provozovně, ke které jste souhlas udělili

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í → AI přístup, 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".
• Seznam Co bude asistent dělat — každé oprávnění na vlastním řádku. Zelená fajfka značí čtení, oranžová tužka zápis.
• Když je mezi oprávněními zápis, přibude upozornění: „Změny vám asistent vždy nejdřív navrhne a provede je až po vašem potvrzení."
• Když máte víc provozoven, je tu výběr Provozovna, ke které přístup povolíte a pod ním vysvětlení, že asistent uvidí data jen z vybrané provozovny a pro další je potřeba spustit připojení znovu. S jedinou provozovnou se místo výběru vypíše její název.
• Řádek Přihlášeni jako <váš e-mail> a vedle něj 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í → AI přístup.

Co přesně smí asistent dělat, určuje seznam oprávnění, o která si klient řekl. Čtecí oprávnění jsou třeba prodejní reporty, ceník, sklad nebo zákazníci; zápisová umožňují upravit položky a sklad nebo založit zákazníka či zaměstnance. Povolujete je jako celek — jednotlivé řádky odškrtnout nejdou, buď souhlasíte s celým seznamem, nebo připojení zamítnete.

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.

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). Klient s oprávněním k úpravě položek zaměstnance zakládat nesmí.

Marže a nákupní ceny: připojený asistent je vidí jen tehdy, když má merchant oprávnění. Běžně připojený AI klient dostane počty kusů a tržby, ale ne nákupní ceny 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í.

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é

Změny dat a potvrzení

Zápisové nástroje mají dvě 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ý zápis vyžaduje samostatné oprávnění, které jste museli povolit na souhlasné obrazovce. Bez něj asistent změnu neprovede.

Každý zápis se zapisuje do auditní stopy provozovny. Provozovna se navíc bere vždy z tokenu, nikdy z toho, co asistent pošle — do cizích dat se zapsat nedá.

Odvolání přístupu

1. Otevřete Nastavení → AI přístup.
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í.

Připojení pro vlastní skripty

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

1. V Nastavení → AI přístup 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"

3. 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.
• Odpověď s isError — neplatné vstupy: období delší než 366 dní, záporná cena, prázdný název.