MCP server pre AI asistentov
eFaktúra vystavuje vzdialený MCP server (Model Context Protocol), cez ktorý Claude, ChatGPT, Claude Code, Cursor alebo váš vlastný agent pracujú priamo s faktúrami, zákazníkmi a výdavkami vašej firmy — bez písania kódu. Autorizácia je štandardný OAuth 2.1, prístup je vždy viazaný na jednu firmu a podlieha rovnakým oprávneniam, limitom a auditu ako REST Agent API.
Pripojenie
| Klient | Postup |
|---|---|
| Claude.ai | Nastavenia → Konektory → Pridať vlastný konektor → URL https://api.efaktura.sk/mcp |
| ChatGPT | Nastavenia → Aplikácie a konektory → Vytvoriť → MCP server URL |
| Claude Code | claude mcp add --transport http efaktura https://api.efaktura.sk/mcp |
| Cursor / iný MCP klient | Streamable HTTP endpoint https://api.efaktura.sk/mcp |
Klient vás presmeruje na prihlásenie do eFaktúry (e-mail + heslo, prípadne 2FA), potom si vyberiete firmu a odsúhlasíte, čo smie asistent robiť. Čítanie je zapnuté, zápisy si zapínate sami. Prístup kedykoľvek zrušíte v aplikácii v Nastavenia → Integrácie → API kľúče (pripojenie má štítok „Asistent").
Technické parametre
| Parameter | Hodnota |
|---|---|
| MCP endpoint | https://api.efaktura.sk/mcp (Streamable HTTP, POST) |
| Protokol | MCP 2026-07-28, spätne aj 2025-06-18 (stateless) |
| Protected resource metadata | https://api.efaktura.sk/.well-known/oauth-protected-resource/mcp |
| Authorization server metadata | https://api.efaktura.sk/.well-known/oauth-authorization-server |
| Autorizácia | OAuth 2.1, authorization code + PKCE (S256), refresh token |
| Registrácia klienta | Dynamic Client Registration alebo Client ID Metadata Document |
| Access token | JWT (EdDSA), platnosť 1 h, audience = MCP endpoint, claim org_id |
| Rate limit a kvóty | Rovnaké ako REST Agent API podľa balíka firmy |
Rozsahy oprávnení (scopes)
Asistent dostane priesečník toho, čo ste odsúhlasili, a toho, čo smie vaša rola vo firme. Identitné scopes openid profile email offline_access slúžia len na priradenie účtu a obnovu tokenu.
| Scope | Čo umožňuje |
|---|---|
| invoice:read | Čítať faktúry a prílohy; Peppol: stav a dôkaz o doručení, overenie príjemcu, preflight XML, prijaté doklady (detail, PDF, XML, prevzatie), udalosti; vozidlá zákazníkov |
| invoice:create | Vystavovať faktúry (s idempotenčným kľúčom) |
| invoice:update | Upravovať obsah faktúry (položky, dátumy, poznámky), meniť stav (uhradená, stornovaná, po splatnosti), pridávať a mazať prílohy |
| invoice:send | Odosielať faktúry do siete Peppol jednotlivo aj hromadne (vyžaduje potvrdenie) a e-mailové upomienky |
| invoice:download | Sťahovať PDF a UBL XML vystavených faktúr |
| contact:read | Čítať zákazníkov a vyhľadávať v registri firiem |
| contact:create | Vytvárať zákazníkov (s idempotenčným kľúčom) |
| receipt:read | Čítať výdavky, dodávateľov, zákazky, štatistiky a platobný QR |
| receipt:create | Evidovať výdavky, nahrávať doklady s OCR, načítať platobný QR, vytvárať dodávateľov a zákazky |
| receipt:update | Upravovať výdavky a zákazky, označovať úhrady, spúšťať OCR, hromadné akcie |
| receipt:approve | Schvaľovať a zamietať výdavky |
| report:read | Mesačný prehľad |
| bank:read | Bankové účty a pohyby na účte |
| inventory:read | Sklady, stav zásob, skladové doklady |
| inventory:write | Vytvárať a potvrdzovať skladové doklady |
| autopark:read | Vozový park: vozidlá, doklady (STK, EK, známky), poistky, pokuty, termíny, predaje na splátky, register vozidiel |
| autopark:write | Zapisovať vozidlá, doklady, poistky, pokuty a splátky |
| contract:read | Zmluvy, ich platby a súhrn |
| contract:create | Vytvárať zmluvy |
| contract:update | Upravovať zmluvy a generovať platby |
Nástroje
Nástroje pokrývajú celé Agent API — všetky moduly, čítanie aj zápis. Zoznam v klientovi zodpovedá udeleným scopes; názvy sú stabilné (snake_case, anglicky), popisy sú slovensko-anglické.
| Modul | Nástroje |
|---|---|
| Faktúry | list_invoices, get_invoice, get_invoice_payments, create_invoice, update_invoice, update_invoice_status, send_invoice_reminder, download_invoice_pdf, download_invoice_xml, list_invoice_attachments, add_invoice_attachment, delete_invoice_attachment |
| Peppol | send_invoice_peppol, send_invoices_peppol_batch, get_peppol_status, get_peppol_sent_evidence, lookup_peppol_recipient, validate_peppol_xml, get_peppol_submission, list_received_peppol_documents, get_received_peppol_document, get_received_peppol_evidence, acknowledge_received_peppol_document, download_received_peppol_pdf, download_received_peppol_xml, list_peppol_events |
| Zákazníci, dodávatelia, register | list_customers, get_customer, create_customer, update_customer, list_vendors, get_vendor, create_vendor, search_companies, get_company_by_ico |
| Výdavky a zákazky | list_expenses, get_expense, create_expense, upload_expense_document, update_expense, approve_expense, reject_expense, mark_expense_paid, process_expense_ocr, bulk_update_expenses, scan_payment_qr, get_expense_payment_qr, get_expense_stats, list_projects, get_project, create_project, update_project |
| Prehľady a banka | get_dashboard_summary, list_bank_accounts, list_bank_movements |
| Sklad | list_warehouses, list_stock_levels, get_stock_level, list_stock_documents, get_stock_document, create_stock_document, confirm_stock_document |
| Vozidlá a Autopark | list_vehicles, get_vehicle, get_vehicle_by_plate, list_fleet_vehicles, create_fleet_vehicle, lookup_vehicle_register, list_vehicle_documents, create_vehicle_document, list_vehicle_fines, create_vehicle_fine, list_vehicle_insurances, create_vehicle_insurance, list_fleet_deadlines, list_installment_sales, get_installment_sale, create_installment_sale, add_installment_item, record_installment_payment |
| Zmluvy | list_contracts, get_contract, list_contract_payments, get_contract_stats, create_contract, update_contract, generate_contract_payments |
Stiahnuté súbory (PDF, XML) prichádzajú ako embedded resource (PDF base64, XML ako text) spolu s názvom súboru a veľkosťou. Zoznamy sú stránkované (page/per_page, limit/offset alebo cursor podľa endpointu). Zápisové nástroje prijímajú idempotency_key, kde ho podporuje API.
send_invoice_peppol bez confirm: true vráti iba náhľad (číslo, príjemca, suma) a nič neodošle. Odoslanie je nevratné a spotrebuje Peppol kredit firmy.Príklady promptov
Vypíš mi faktúry po splatnosti a pri každej napíš, koľko dní mešká.
Vystav faktúru pre Novák s.r.o. za 12 hodín konzultácií po 60 € bez DPH, splatnosť 14 dní.
Over, či je firma s IČO 36631124 v sieti Peppol, a ak áno, pošli jej faktúru 2026-0142.
Aké boli moje výdavky za palivo v auguste 2026?
Stiahni mi PDF faktúry 2026-0142 a pošli ho ako prílohu.
Ktoré doklady čakajú na schválenie? Schváľ všetky od Slovnaftu.
Aké pohyby boli na firemnom účte minulý týždeň a ktoré nie sú spárované?
Čo mi vo vozovom parku vyprší do 30 dní (STK, poistky, známky)?
Koľko kusov produktu ABC-1 máme na sklade a v ktorom sklade?Chyby, ktoré asistent dostane
| Situácia | Odpoveď nástroja |
|---|---|
| Zrušené pripojenie | HTTP 401, error connection_revoked — pripojte asistenta znova |
| Chýbajúce oprávnenie | isError s kódom FORBIDDEN / INSUFFICIENT_SCOPE a rolou, ktorá chýba |
| Vyčerpaná kvóta dokladov | isError s hint „Navýšte balík v Nastavenia → Predplatné“ |
| Prekročený rate limit | isError s retryAfterSeconds |
Súkromie a dáta
Asistent vidí iba údaje firmy, ktorú ste vybrali, a iba v rozsahu odsúhlasených scopes. Každé volanie sa zapisuje do auditu API (rovnaká tabuľka ako pre API kľúče) a uchováva sa podľa retenčnej politiky API logov. eFaktúra neposiela dáta poskytovateľom AI modelov — dáta odchádzajú výlučne do klienta, ktorý ste pripojili. Tokeny sú viazané na náš endpoint (RFC 8707) a nedajú sa použiť inde. Zásady ochrany osobných údajov: efaktura.sk/ochrana-osobnych-udajov.
Sandbox
Firmy v sandbox režime (testovací Peppol) dostanú kľúč v režime test: odoslanie cez Peppol ide do testovacej siete a nikdy do produkcie. Vhodné na vyskúšanie promptov pred ostrým nasadením.