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

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

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í AI klienta

Doporučený způsob nevyžaduje kopírování hesel ani klíčů.

  1. Zadejte adresu serveru https://mcp.smable.cz/mcp do svého AI klienta.
  2. Klient otevře prohlížeč a vyzve vás k přihlášení do Smable.
  3. Zobrazí se obrazovka se seznamem oprávnění, o která asistent žádá. Souhlas se váže na provozovnu, do které jste právě přihlášeni.
  4. Klikněte na Povolit.

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.

Přístupový token platí 15 minut a klient si ho po dobu 30 dní sám obnovuje — připojení tedy nemusíte opakovat.

Pokud váš klient neumí registraci sám, vytvořte mu přístup v Nastavení → AI přístup a Client ID z něj vložte do klienta ručně.

Do Claude Code přidáte server jedním příkazem:

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

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ží.

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.

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ástroj Co vrací Parametry
report_items prodeje po položkách — počet kusů, tržba, marže 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 vs. náklady po dnech date_from, date_to
search_help články nápovědy k dotazu query, volitelně limit (1–20, výchozí 5)

Stav skladu ani ceník se 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

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