Server MCP Invoiso

Invoiso berbicara dalam Model Context Protocol, jadi klien MCP — Claude, ChatGPT, atau apa pun yang memahaminya — dapat membaca dan mengelola faktur, tagihan, kontak, stok, dan laporan di ruang kerja invoiso Anda. Halaman ini berisi semua yang Anda butuhkan untuk menghubungkannya.

Endpoint

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

Sebagian besar orang hanya perlu URL-nya. Tambahkan sebagai konektor khusus di ChatGPT atau server MCP jarak jauh di Claude, lalu masuk ke invoiso seperti biasa — tidak perlu kunci API. Klien menemukan sendiri cara autentikasinya: panggilan tanpa autentikasi menjawab 401 dengan header WWW-Authenticate yang menunjuk ke https://www.invoiso.com/.well-known/oauth-protected-resource, yang menyebutkan server otorisasi dan scope yang harus diminta.

Menghubungkan

1. Tambahkan https://www.invoiso.com/api/mcp ke klien Anda sebagai server MCP jarak jauh.
2. Klien mengarahkan Anda ke halaman masuk invoiso. Masuk seperti biasa.
3. Setujui akses yang dijelaskan layar persetujuan. Layar itu menyebutkan ruang kerja yang Anda hubungkan.
4. Anda sudah terhubung. Tanyakan sesuatu tentang pembukuan Anda — “berapa yang saya tagihkan bulan lalu?” adalah pertanyaan pertama yang baik, karena tidak butuh izin selain membaca.

Scope yang diminta adalah openid, email, profile dan user:org:read. Yang terakhir memberi tahu kami ruang kerja mana yang Anda hubungkan; tanpa itu server menolak alih-alih menebak — lihat di bawah.

Ruang kerja mana yang terhubung

Anda terhubung ke ruang kerja yang sedang aktif di peramban Anda saat Anda menyetujui koneksi. Layar persetujuan menyebutkannya. Ini aturan yang sama seperti di peramban — satu sesi berada di satu ruang kerja pada satu waktu — dan artinya berpindah ruang kerja di invoiso tidak mengubah apa yang dilihat klien MCP Anda.

Untuk mengarahkan klien ke ruang kerja lain: pindah dulu ke ruang kerja itu di invoiso, lalu hapus dan tambahkan lagi koneksinya di klien Anda. Anda akan melewati persetujuan sekali lagi, dan token barunya membawa ruang kerja yang baru.

Jika server tidak bisa memastikan token itu untuk ruang kerja yang mana, ia menjawab 403 dengan error="insufficient_scope" yang menyebutkan scope yang harus diminta, bukan memilih sendiri. Memilih akan lebih buruk daripada menolak: jawaban keliru yang masuk akal adalah ruang kerja pribadi Anda yang kosong, dan Anda akan menyimpulkan invoiso kehilangan pembukuan Anda.

Apa yang bisa dilakukan paket Anda

Semuanya tersedia untuk asisten di dalam invoiso pada setiap paket. Yang berbeda pada klien MCP eksternal adalah boleh tidaknya menulis.

Koneksi hanya-baca bukan klien yang dikurangi — itu semua alat yang hanya melaporkan. Menulis dari klien eksternal dimulai pada Business. Minta koneksi hanya-baca mengubah sesuatu dan ia akan mengatakannya dalam satu kalimat tanpa mengubah apa pun, bukan gagal secara tidak jelas.

Apa yang dilakukan alat-alatnya

Ada 167 alat. 63 di antaranya hanya melaporkan; sisanya menulis. Setiap alat membawa tiga anotasi yang didefinisikan MCP — readOnlyHint, destructiveHint, dan openWorldHint — sehingga klien Anda bisa bertanya sebelum melakukan sesuatu yang tak bisa dibatalkan. 15 di antaranya bisa mengubah sesuatu di luar invoiso: mengirim surel, menerbitkan halaman pembayaran, menulis ke Xero atau QuickBooks. Itulah yang sebaiknya dikonfirmasi klien Anda.

Jumlah selalu dinyatakan dua kali

Sebuah ruang kerja bisa memuat dokumen dalam beberapa mata uang. Alat apa pun yang mengembalikan jumlah akan mengembalikannya dalam mata uang dokumen itu sendiri dan dalam mata uang pelaporan ruang kerja, dikonversi pada kurs yang dipatok ke dokumen tersebut. Hanya yang kedua yang bisa dibandingkan antardokumen, dan instruksi server melarang model menjumlahkan dua nilai dalam mata uang berbeda. Bila tidak ada kurs yang mencakup suatu tanggal, angka pelaporannya adalah null, bukan nol.

Total berasal dari alat pelaporan

run_report menjawab pertanyaan “berapa”. Alat pendaftar membuat daftar; menjumlahkan daftar bukan aritmetika yang sama — draf dan nota kredit dihitung berbeda — dan deskripsi tiap alat menyebutkan yang mana dia.

Apa yang dibaca server, dan apa yang disimpannya

Pemanggilan alat membaca dan menulis data ruang kerja Anda sendiri: faktur, tagihan, kontak, produk, dan pengaturan. Responsnya memuat catatan bisnis yang ditanyakan — untuk kontak berarti namanya, dan bisa berarti alamat surel, alamat pos, atau nomor pajak, karena itulah yang muncul pada faktur.

Server tidak menyimpan salinan percakapan secara terpisah, tidak mengirim respons alat ke mana pun selain kembali ke klien yang bertanya, dan tidak pernah mengembalikan kredensial, kunci API, atau token OAuth — milik Anda maupun milik layanan yang terhubung. Apa yang kami lakukan dengan data secara umum, termasuk pihak ketiga mana menerima apa, ada di kebijakan privasi, dan ketentuan berlaku untuk koneksi ini seperti untuk koneksi lain.

Memutus koneksi

Hapus koneksinya di klien MCP Anda. Itu sudah cukup: token adalah satu-satunya yang memberi akses, dan tidak ada apa pun di sisi kami yang terus bekerja tanpanya. Menghapus akun invoiso Anda menghapus semua yang ada di belakangnya — kebijakan privasi menjelaskan apa artinya dan berapa lama prosesnya.

Detail protokol

Server menegosiasikan 2025-06-18, 2025-03-26 dan 2024-11-05, menjawab dengan versi terbaru yang dipahami olehnya dan oleh klien. Versi yang tidak dikenali dijawab dengan versi terbaru yang kami dukung, bukan ditolak, sebagaimana diminta spesifikasi.

Otorisasi mengikuti OAuth 2.1 dengan PKCE. Penemuannya adalah metadata protected-resource RFC 9728 di https://www.invoiso.com/.well-known/oauth-protected-resource, dan server otorisasi menerbitkan dokumen penemuan RFC 8414 sekaligus OpenID Connect. Klien mendaftarkan dirinya sendiri lewat pendaftaran klien dinamis (RFC 7591), itulah sebabnya langkah-langkah di atas tidak meminta apa pun selain URL. Endpoint pendaftaran hanya diumumkan pada dokumen RFC 8414; klien yang hanya membaca dokumen OpenID Connect tidak akan menemukannya dan memerlukan client id yang sudah ditentukan di bawah.

Jika klien Anda tidak bisa mendaftar sendiri dan meminta client id, kirim surel ke support@invoiso.com dan kami akan memberikannya. Biarkan client secret kosong — kliennya publik dan mengautentikasi dengan PKCE.

Token diverifikasi terhadap JWKS instansi kami sendiri dan harus membawa issuer kami serta scope yang menyebutkan ruang kerja Anda. Token yang diterbitkan oleh pemasangan invoiso lain, atau instansi Clerk lain, ditolak. Token dari aplikasi berbeda yang terdaftar pada instansi ini tidak bisa dibedakan dari milik kami dan diterima — itulah arti pendaftaran terbuka, dan karena itu layar persetujuan yang menyebutkan aplikasi peminta patut dibaca sebelum Anda menyetujuinya.

Jika ada yang salah

Kirim surel ke support@invoiso.com berisi apa yang diminta klien Anda dan apa yang kembali. 401 biasanya berarti koneksinya perlu disetujui ulang; 403 yang menyebut sebuah scope berarti klien tidak memintanya; dan penolakan yang menyebut paket Anda adalah gerbang hanya-baca di atas, bukan kerusakan.