Invoiso MCP serveris

Invoiso kalba Model Context Protocol kalba, tad MCP klientas — „Claude“, „ChatGPT“ ar bet kuris kitas, mokantis šį protokolą — gali skaityti ir tvarkyti jūsų invoiso darbo srities sąskaitas, išlaidas, kontaktus, atsargas ir ataskaitas. Šiame puslapyje yra viskas, ko reikia prijungimui.

Galinis taškas

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

Daugumai užtenka vien URL. Pridėkite jį kaip pasirinktinę jungtį „ChatGPT“ arba kaip nuotolinį MCP serverį „Claude“, tada prisijunkite prie invoiso kaip įprasta — API rakto nereikia. Klientas pats išsiaiškina, kaip autentifikuotis: neautentifikuotas kreipinys atsako 401 su antrašte WWW-Authenticate, nurodančia https://www.invoiso.com/.well-known/oauth-protected-resource, kur įvardytas autorizacijos serveris ir prašomos apimtys.

Prijungimas

1. Pridėkite https://www.invoiso.com/api/mcp savo kliente kaip nuotolinį MCP serverį.
2. Klientas nukreipia jus į invoiso prisijungimą. Prisijunkite kaip įprasta.
3. Patvirtinkite prieigą, kurią aprašo sutikimo langas. Jame įvardijama jūsų jungiama darbo sritis.
4. Prisijungta. Paklauskite savo kliento ko nors apie savo apskaitą — „kiek išrašiau praėjusį mėnesį?“ yra geras pirmas klausimas, nes jam nereikia jokių teisių, išskyrus skaitymą.

Prašomos apimtys yra openid, email, profile ir user:org:read. Paskutinė nurodo, kurią darbo sritį jungiate; be jos serveris atsisako, o ne spėja — žr. toliau.

Su kuria darbo sritimi esate prisijungę

Esate prisijungę prie tos darbo srities, kuri jūsų naršyklėje buvo aktyvi, kai patvirtinote ryšį. Sutikimo lange ji įvardijama. Tai ta pati taisyklė, kurios laikosi naršyklė — sesija vienu metu yra vienoje darbo srityje — ir tai reiškia, kad darbo srities perjungimas invoiso nekeičia to, ką mato jūsų MCP klientas.

Norėdami nukreipti klientą į kitą darbo sritį: pirmiausia invoiso perjunkite į ją, tada kliente pašalinkite ryšį ir pridėkite jį iš naujo. Sutikimo langas bus parodytas dar kartą, o naujas prieigos raktas turės naują darbo sritį.

Jei serveris negali nustatyti, kuriai darbo sričiai skirtas prieigos raktas, jis atsako 403 su error="insufficient_scope" ir nurodo prašomą apimtį, o ne pasirenka pats. Pasirinkti būtų blogiau nei atsisakyti: tikėtinas klaidingas atsakymas yra jūsų tuščia asmeninė darbo sritis, ir jūs nuspręstumėte, kad invoiso pametė jūsų apskaitą.

Ką gali jūsų planas

Asistentui invoiso viduje viskas prieinama bet kuriame plane. Kas keičiasi išoriniame MCP kliente — ar jam leidžiama rašyti.

Tik skaitymo ryšys nėra apribotas klientas — tai visi įrankiai, kurie tik praneša. Rašymas iš išorinio kliento prasideda nuo Business. Paprašius tik skaitymo ryšio ką nors pakeisti, jis tai pasako vienu sakiniu ir nieko nekeičia, o ne sutrinka neaiškiai.

Ką daro įrankiai

Iš viso yra 167 įrankiai. 63 iš jų tik praneša; likusieji rašo. Kiekvienas įrankis turi tris MCP apibrėžtas anotacijas — readOnlyHint, destructiveHint ir openWorldHint — kad jūsų klientas galėtų paklausti, prieš atlikdamas ką nors negrįžtamo. 15 iš jų gali pakeisti kai ką už invoiso ribų: išsiųsti el. laišką, paskelbti mokėjimo puslapį, įrašyti į „Xero“ ar „QuickBooks“. Būtent šiuos verta patvirtinti.

Sumos visada nurodomos dukart

Darbo srityje gali būti dokumentų keliomis valiutomis. Bet kuris sumą grąžinantis įrankis pateikia ją paties dokumento valiuta ir darbo srities ataskaitine valiuta, perskaičiuotą pagal prie to dokumento pririštą kursą. Tik antroji yra palyginama tarp dokumentų, o serverio nurodymai liepia modeliui niekada nesudėti dviejų skirtingų valiutų sumų. Kai jokio kurso datai nebuvo, ataskaitinė reikšmė yra null, o ne nulis.

Sumos gaunamos iš ataskaitų įrankio

run_report atsako į klausimus „kiek“. Sąrašų įrankiai pateikia sąrašus; sudėti sąrašą — ne ta pati aritmetika (juodraščiai ir kreditiniai dokumentai skaičiuojami kitaip), o kiekvieno įrankio aprašas nurodo, kuris jis yra.

Ką serveris skaito ir ką saugo

Įrankio iškvietimas skaito ir rašo jūsų darbo srities duomenis: jūsų sąskaitas, išlaidas, kontaktus, prekes ir nustatymus. Atsakymuose pateikiami tie verslo įrašai, kurių buvo prašoma — kontakto atveju tai vardas, o gali būti ir el. pašto adresas, pašto adresas ar mokesčių mokėtojo kodas, nes būtent tai matoma sąskaitoje.

Serveris nesaugo atskiros pokalbio kopijos, nesiunčia jokio įrankio atsakymo niekur kitur, tik atgal prašiusiam klientui, ir niekada negrąžina prisijungimo duomenų, API raktų ar OAuth prieigos raktų — nei jūsų, nei prijungtos paslaugos. Ką apskritai darome su duomenimis, įskaitant tai, kurios trečiosios šalys ką gauna, aprašyta privatumo politikoje, o sąlygos galioja šiam ryšiui kaip ir bet kuriam kitam.

Atjungimas

Pašalinkite ryšį savo MCP kliente. To pakanka: prieigos raktas yra vienintelis dalykas, suteikiantis prieigą, ir be jo mūsų pusėje niekas nebeveikia. Ištrynus invoiso paskyrą pašalinama viskas, kas už jos — ką tai reiškia ir kiek trunka, rašoma privatumo politikoje.

Protokolo detalės

Serveris derina 2025-06-18, 2025-03-26 ir 2024-11-05 ir atsako naujausia versija, kurią supranta ir jis, ir klientas. Į neatpažintą versiją atsakoma naujausia palaikoma, o ne atmetama — to reikalauja specifikacija.

Autorizacija atitinka OAuth 2.1 su PKCE. Aptikimas — RFC 9728 apsaugoto ištekliaus metaduomenys adresu https://www.invoiso.com/.well-known/oauth-protected-resource, o autorizacijos serveris skelbia ir RFC 8414, ir OpenID Connect aptikimo dokumentus. Klientai registruojasi patys per dinaminę kliento registraciją (RFC 7591) — todėl aukščiau nurodyti veiksmai neprašo nieko, išskyrus URL. Registracijos galinis taškas skelbiamas tik RFC 8414 dokumente; klientas, skaitantis vien OpenID Connect dokumentą, jo neras ir jam prireiks toliau nurodyto iš anksto apibrėžto kliento ID.

Jei jūsų klientas negali užsiregistruoti pats ir prašo kliento ID, parašykite support@invoiso.com ir mes jį duosime. Kliento slaptažodį palikite tuščią — klientas yra viešas ir autentifikuojasi per PKCE.

Prieigos raktai tikrinami pagal mūsų pačių egzemplioriaus JWKS ir privalo turėti mūsų išdavėją bei apimtį, įvardijančią jūsų darbo sritį. Kito invoiso diegimo ar kitos „Clerk“ instancijos išduotas raktas atmetamas. Kitos programos, registruotos šiame egzemplioriuje, raktas nuo mūsų neatskiriamas ir priimamas — būtent tai reiškia atvira registracija, ir todėl verta perskaityti sutikimo langą, kuriame įvardyta prašanti programa, prieš patvirtinant.

Jei kas nors negerai

Parašykite support@invoiso.com, ką jūsų klientas paprašė ir kas grįžo. 401 paprastai reiškia, kad ryšį reikia patvirtinti iš naujo; 403 su nurodyta apimtimi reiškia, kad klientas jos neprašė; o atsisakymas, kuriame įvardytas jūsų planas, yra aukščiau aprašytas tik skaitymo ribojimas, o ne triktis.