Pre vývojárov
AI asistent nad vašimi dokladmi
Pripojte Claude, Cursor alebo iný nástroj k Kvitosu cez MCP a pýtajte sa na to, čo aj tak riešite: kto mi dlhuje, bude mi v marci na výplaty, prečo tá faktúra neodišla. Bez exportovania tabuliek.
Server beží u vás, s vaším kľúčom · dokumentácia API
Čo to je
MCP (Model Context Protocol) je spôsob, akým AI asistenti pristupujú k cudzím údajom. @kvitos/mcp je malý program, ktorý beží na vašom počítači vedľa asistenta a hovorí s naším API tým istým kľúčom, aký by použil váš skript. Nič z toho nehostíme — kľúč neopustí stroj, na ktorý ste ho vložili.
1. Vydajte kľúč pre asistenta
Po prihlásení v Nastaveniach → API kľúče zvoľte predvoľbu AI asistent (MCP). Vydajte asistentovi vlastný kľúč — nie ten, ktorým fakturuje e-shop. Kľúč sa ukáže raz; potom už len jeho prefix.
Predvoľba obsahuje presne toto: documents:read, expenses:read, reports:read, lookup:read, suggestions:read a suggestions:write. Žiadny zápisový rozsah na doklady, mzdy ani nastavenia: kľúč bez rozsahu na mzdy sa k mzdám nedostane, aj keby o ne model požiadal.
Skúšate? Zaškrtnite testovací kľúč — sandbox má vlastné doklady a nič z neho neodíde do Peppolu ani Finančnej správe.
2. Vložte ho do konfigurácie
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"kvitos": {
"command": "npx",
"args": ["-y", "@kvitos/mcp"],
"env": {
"KVITOS_API_KEY": "kvi_live_…",
"KVITOS_MCP_READONLY": "1"
}
}
}
}Po uložení klienta zavrite celý a spustite znova — konfiguráciu číta pri štarte.
| Premenná | Čo robí |
|---|---|
KVITOS_API_KEY | Povinné. Kľúč z predchádzajúceho kroku. |
KVITOS_API_URL | Predvolene https://api.kvitos.sk. |
KVITOS_MCP_READONLY=1 | Asistent neurobí ani koncept. Odporúčame, kým si na neho zvyknete. |
3. Overte, že to funguje
Spýtajte sa asistenta: „Čo smieš v Kvitose?" Zavolá describe_access a odpovie, do ktorej firmy kľúč patrí, v akom je režime, aké má rozsahy a ktoré nástroje s ním budú fungovať — aj s dôvodom pri tých, ktoré nie.
Tým sa vyhnete najčastejšiemu zmätku: asistent narazí na 403 uprostred odpovede a ohlási to ako poruchu, hoci je to úzko vydaný kľúč, ktorý je tak vydaný naschvál.
Nástroje
| Nástroj | Potrebný rozsah | Čo robí |
|---|---|---|
describe_access | žiadny | Čo tento kľúč smie a ktoré nástroje s ním budú fungovať. |
list_unpaid_invoices | documents:read | Kto dlhuje a čo je po splatnosti. |
get_document | documents:read | Jeden doklad podľa čísla. |
check_document | documents:read | Prečo sa doklad (ne)vystaví — pravidlá EN 16931 a Peppol BIS nanečisto. |
explain_rejection | documents:read | Prečo doklad neodišiel: stav doručenia, text chyby a čo hovoria pravidlá. |
find_duplicates | expenses:read | Prijaté faktúry, ktoré vyzerajú ako zapísané dvakrát. |
suggest_posting | expenses:read + suggestions:write | Návrh zaúčtovania nákladu z toho, kam ste dodávateľa účtovali doteraz. Nezaúčtuje nič. |
get_receivables | reports:read | Saldokonto po vekových košoch. |
get_cashflow | reports:read | Predpoveď cashflow aj s tým, čo nevie. |
check_vat_number | lookup:read | Overenie IČ DPH vo VIES. |
draft_invoice | documents:write | Pripraví koncept. Nevystaví ho. |
Odpovede sú vety, nie JSON. Model, ktorý dostane blob údajov, ho zhrnie — a jeho zhrnutie je ďalšie miesto, kde sa číslo môže cestou k človeku zmeniť.
Vaše údaje, váš asistent
Nástroje posielajú obsah dokladov — vrátane údajov o odberateľoch — tomu modelu, ktorého ste si zvolili. Poskytovateľa vyberáte vy a vzťah s ním máte vy; Kvitos v tom prenose nie je sprostredkovateľ a nemá ako doň vidieť.
- Ak vaše údaje nesmú opustiť EÚ alebo váš počítač, riešte to voľbou asistenta — model, ktorý beží lokálne, alebo poskytovateľ so spracovaním v EÚ.
- Ak spracúvate osobné údaje, doplňte si asistenta do vlastnej informácie o spracúvaní a majte s jeho poskytovateľom zmluvu.
- Čo kľúč čítal, vidíte v audit logu; každý návrh nesie prefix kľúča, ktorým prišiel.
- Kľúč zrušíte v Nastaveniach jedným kliknutím — od tej chvíle asistent nevidí nič.