Pelayan MCP Invoiso

Invoiso bertutur dalam Model Context Protocol, jadi klien MCP — Claude, ChatGPT, atau apa-apa sahaja yang memahaminya — boleh membaca dan mengurus invois, bil, kenalan, stok dan laporan dalam ruang kerja invoiso anda. Halaman ini ialah apa yang anda perlukan untuk menyambungkannya.

Titik akhir

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

Kebanyakan orang hanya perlukan URL. Tambahkannya sebagai penyambung tersuai dalam ChatGPT atau pelayan MCP jauh dalam Claude, kemudian log masuk ke invoiso seperti biasa — tiada kunci API diperlukan. Klien menemui sendiri cara mengesahkan diri: panggilan tanpa pengesahan menjawab 401 dengan pengepala WWW-Authenticate yang menunjuk ke https://www.invoiso.com/.well-known/oauth-protected-resource, yang menamakan pelayan kebenaran dan skop yang perlu diminta.

Menyambung

1. Tambahkan https://www.invoiso.com/api/mcp pada klien anda sebagai pelayan MCP jauh.
2. Klien membawa anda ke log masuk invoiso. Log masuk seperti biasa.
3. Luluskan akses yang diterangkan oleh skrin kebenaran. Ia menamakan ruang kerja yang anda sambungkan.
4. Anda telah bersambung. Tanya klien anda sesuatu tentang buku akaun anda — “berapa yang saya invois bulan lalu?” ialah soalan pertama yang baik, kerana ia tidak memerlukan kebenaran selain membaca.

Skop yang diminta ialah openid, email, profile dan user:org:read. Yang terakhir memberitahu kami ruang kerja yang mana yang anda sambungkan; tanpanya pelayan menolak dan bukan meneka — lihat di bawah.

Ruang kerja mana yang disambungkan

Anda disambungkan ke ruang kerja yang aktif dalam pelayar anda semasa anda meluluskan sambungan itu. Skrin kebenaran menamakannya. Ini peraturan yang sama seperti pelayar — satu sesi berada dalam satu ruang kerja pada satu masa — dan ini bermakna bertukar ruang kerja dalam invoiso tidak mengubah apa yang dilihat oleh klien MCP anda.

Untuk mengarahkan klien ke ruang kerja lain: tukar dahulu ke ruang kerja itu dalam invoiso, kemudian buang dan tambah semula sambungan dalam klien anda. Anda akan melalui kebenaran sekali lagi, dan token baharu membawa ruang kerja yang baharu.

Jika pelayan tidak dapat menentukan token itu untuk ruang kerja yang mana, ia menjawab 403 dengan error="insufficient_scope" yang menamakan skop yang perlu diminta, bukannya memilih sendiri. Memilih akan lebih buruk daripada menolak: jawapan salah yang munasabah ialah ruang kerja peribadi anda yang kosong, dan anda akan menyimpulkan invoiso telah kehilangan buku akaun anda.

Apa yang boleh dilakukan pelan anda

Semuanya tersedia untuk pembantu di dalam invoiso pada setiap pelan. Apa yang berubah pada klien MCP luaran ialah sama ada ia boleh menulis.

Sambungan baca sahaja bukan klien yang dikurangkan — ia setiap alat yang hanya melaporkan. Menulis daripada klien luaran bermula pada Business. Minta sambungan baca sahaja untuk mengubah sesuatu dan ia akan menyatakannya dalam satu ayat tanpa mengubah apa-apa, bukan gagal secara kabur.

Apa yang dilakukan oleh alat

Terdapat 167 alat. 63 daripadanya hanya melaporkan; selebihnya menulis. Setiap alat membawa tiga anotasi yang ditakrifkan MCP — readOnlyHint, destructiveHint dan openWorldHint — supaya klien anda boleh bertanya sebelum melakukan sesuatu yang tidak boleh diundur. 15 daripadanya boleh mengubah sesuatu di luar invoiso: menghantar e-mel, menerbitkan halaman pembayaran, menulis ke Xero atau QuickBooks. Itulah yang berbaloi disahkan oleh klien anda.

Jumlah sentiasa dinyatakan dua kali

Satu ruang kerja boleh memuatkan dokumen dalam beberapa mata wang. Mana-mana alat yang memulangkan jumlah akan memulangkannya dalam mata wang dokumen itu sendiri dan dalam mata wang pelaporan ruang kerja, ditukar pada kadar yang dipasak pada dokumen itu. Hanya yang kedua boleh dibandingkan antara dokumen, dan arahan pelayan melarang model menambah dua jumlah dalam mata wang berbeza. Jika tiada kadar pertukaran meliputi sesuatu tarikh, angka pelaporannya ialah null, bukan sifar.

Jumlah datang daripada alat pelaporan

run_report menjawab soalan “berapa”. Alat penyenaraian menyenaraikan; menjumlahkan senarai bukan aritmetik yang sama — draf dan nota kredit dikira berbeza — dan perihal setiap alat menyatakan yang mana satu.

Apa yang dibaca pelayan, dan apa yang disimpannya

Panggilan alat membaca dan menulis data ruang kerja anda sendiri: invois, bil, kenalan, produk dan tetapan anda. Responsnya membawa rekod perniagaan yang ditanya — bagi kenalan bermakna namanya, dan mungkin alamat e-mel, alamat pos atau nombor pendaftaran cukai, kerana itulah yang muncul pada invois.

Pelayan tidak menyimpan salinan perbualan yang berasingan, tidak menghantar respons alat ke mana-mana selain kembali kepada klien yang bertanya, dan tidak pernah memulangkan bukti kelayakan, kunci API atau token OAuth — milik anda mahupun milik perkhidmatan yang disambungkan. Apa yang kami lakukan dengan data secara amnya, termasuk pihak ketiga mana menerima apa, ada dalam dasar privasi, dan terma terpakai pada sambungan ini seperti pada mana-mana sambungan lain.

Memutuskan sambungan

Buang sambungan itu dalam klien MCP anda. Itu sudah memadai: token ialah satu-satunya perkara yang memberi akses, dan tiada apa-apa di pihak kami terus berfungsi tanpanya. Memadam akaun invoiso anda membuang segala-galanya di sebaliknya — dasar privasi menerangkan maksudnya dan berapa lama ia mengambil masa.

Butiran protokol

Pelayan merundingkan 2025-06-18, 2025-03-26 dan 2024-11-05, menjawab dengan versi terbaharu yang difahami olehnya dan oleh klien. Versi yang tidak dikenali dijawab dengan versi terbaharu yang kami sokong, bukan ditolak, seperti yang diminta oleh spesifikasi.

Kebenaran mengikut OAuth 2.1 dengan PKCE. Penemuan ialah metadata sumber dilindungi RFC 9728 di https://www.invoiso.com/.well-known/oauth-protected-resource, dan pelayan kebenaran menerbitkan dokumen penemuan RFC 8414 dan OpenID Connect. Klien mendaftar sendiri melalui pendaftaran klien dinamik (RFC 7591), sebab itulah langkah-langkah di atas tidak meminta apa-apa selain URL. Titik akhir pendaftaran diiklankan pada dokumen RFC 8414 sahaja; klien yang hanya membaca dokumen OpenID Connect tidak akan menemuinya dan memerlukan id klien pratakrif di bawah.

Jika klien anda tidak boleh mendaftar sendiri dan meminta id klien, e-mel support@invoiso.com dan kami akan memberikan satu. Biarkan rahsia klien kosong — kliennya awam dan mengesahkan diri dengan PKCE.

Token disahkan terhadap JWKS instans kami sendiri dan mesti membawa penerbit kami serta skop yang menamakan ruang kerja anda. Token yang dikeluarkan oleh pemasangan invoiso lain, atau instans Clerk lain, ditolak. Token daripada aplikasi berbeza yang didaftarkan pada instans ini tidak dapat dibezakan daripada milik kami dan diterima — itulah maksud pendaftaran terbuka, dan sebab itu skrin kebenaran yang menamakan aplikasi yang meminta berbaloi dibaca sebelum anda meluluskannya.

Jika ada yang tidak kena

E-mel support@invoiso.com dengan apa yang klien anda minta dan apa yang kembali. 401 biasanya bermakna sambungan perlu diluluskan semula; 403 yang menamakan sesuatu skop bermakna klien tidak memintanya; dan penolakan yang menamakan pelan anda ialah pagar baca sahaja di atas, bukan kerosakan.