MCP integrasi
Untuk organisasi modular, organisasi yang terhubung memerlukan modul CRM yang aktif serta cakupan yang diwajibkan oleh integrasi. API yang mendasarinya mengembalikan HTTP 403 dengan module_not_active jika akses CRM tidak tersedia. Atasi akses modul di Subscription sebelum mencoba lagi; mengganti kunci API saja tidak akan memperbaiki kesalahan ini.
Scoutello menyediakan server Model Context Protocol (MCP) jarak jauh untuk akses terkontrol ke data organisasi. Server ini menggunakan integrasi, kunci API, cakupan, pemeriksaan tenant, batas laju, dan perilaku rekaman yang sama seperti Scoutello REST API.
Gunakan MCP saat klien atau agen AI perlu menemukan dan memanggil operasi Scoutello sebagai alat. Gunakan REST saat aplikasi memerlukan endpoint HTTP konvensional atau klien OpenAPI yang dibuat secara otomatis. Kedua antarmuka menggunakan kontrak data dasar yang sama.
Sebelum menghubungkan
Orang dengan hak administrasi organisasi harus membuat integrasi di Pengaturan organisasi → Developer/API. Saat membuat atau merotasi kuncinya:
- Pilih hanya cakupan baca dan tulis yang diperlukan klien MCP.
- Simpan kunci
sctl_api_lengkap saat ditampilkan. Scoutello hanya menampilkannya satu kali. - Simpan kunci tersebut di rahasia atau konfigurasi lingkungan klien MCP, bukan di kontrol versi.
Kunci integrasi yang sama dapat digunakan untuk memanggil REST dan MCP. Membuat kunci khusus MCP kedua tidak diperlukan dan tidak disarankan. Kunci sctl_mcp_ lama tidak diterima.
Nilai koneksi
Konfigurasikan klien dengan nilai berikut:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Ganti YOUR_API_KEY dengan kunci integrasi yang telah disimpan. Format konfigurasi klien berbeda-beda, tetapi transport, URL, dan header HTTP di atas tetap sama. Jika klien tidak dapat menetapkan Authorization, kunci dapat dikirim dalam x-api-key sebagai gantinya. Jangan konfigurasikan kedua header tersebut.
URL https://admin.scoutello.com/api/mcp lama tetap tersedia sebagai alias kompatibilitas. Koneksi baru sebaiknya menggunakan endpoint /api/v1/mcp berversi.
Memverifikasi koneksi
Setelah klien terhubung, panggil alat whoami terlebih dahulu. Alat ini mengembalikan integrasi dan organisasi saat ini, informasi kedaluwarsa dan penggunaan kredensial, status batas laju, serta cakupan yang diberikan tanpa membuka rekaman organisasi.
Jika whoami menunjukkan organisasi atau integrasi yang tidak diharapkan, putuskan koneksi klien dan perbaiki kuncinya sebelum memanggil alat lain.
Alat dan cakupan
Server MCP hanya mengiklankan alat yang diberikan oleh kunci saat ini. Klien tidak dapat menemukan atau memanggil alat tulis hanya dengan cakupan baca yang sesuai.
| Cakupan API | Alat MCP |
|---|---|
contacts.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert (termasuk upsert peserta) |
milestones.read | milestones_list, milestones_get, milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
mail-drafts.read | mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert (hanya untuk persiapan peninjauan oleh manusia) |
tags.read | tags_list |
whoami selalu tersedia untuk koneksi yang terautentikasi. Input dan hasil alat mengikuti skema serta envelope respons yang sama seperti operasi REST terkait.
contacts_list menerima search terbatas pada nama depan/belakang dan nama perusahaan, type, status, serta tagIds (array berisi 1–50 ID yang cocok dengan tag yang dipilih). Semua token pencarian harus cocok dengan bidang nama; semua filter digabungkan dengan AND. Terapkan filter ini pada setiap halaman kursor. Misalnya, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } menemukan akun yang sudah ada dan cocok tanpa memindai seluruh inventaris.
Kontak CRM nonanggota yang ditautkan ke login Scoutello dapat dibaca dan dijadikan referensi, sementara bidang keanggotaan/akun tetap tersembunyi dan pengeditan kontak tetap terlindungi. Upsert yang hanya menggunakan tautan eksternal dapat mendaftarkan kontak yang dapat dibaca menggunakan externalId, scoutelloId, dan externalUpdatedAt opsional; jangan sertakan bidang CRM apa pun. Pada percobaan ulang/pembaruan metadata berikutnya, jangan sertakan scoutelloId. Lihat batasan kontak dan aturan penautan.
Bekerja dengan aman
Alat batch-upsert dapat langsung mengubah data Scoutello. Alat ini idempoten untuk integrasi dan ID eksternal yang sama. Namun, tetap periksa sumber daya, organisasi, dan cakupan yang dimaksud sebelum menerapkan perubahan.
Setel mode ke validate untuk menjalankan pencocokan dan validasi tanpa menulis. Setelah memeriksa hasilnya, ulangi dengan mode: "apply" untuk menerapkan rekaman yang valid. MCP tidak menyediakan operasi penghapusan.
Menjeda integrasi menolak permintaan REST dan MCP dengan kuncinya. Rotasi mengganti kredensial. Pencabutan menonaktifkan semua kredensial integrasi secara permanen.
Pemecahan masalah
| Hasil | Yang perlu diperiksa |
|---|---|
Kesalahan autentikasi 401 | Pastikan kunci lengkap tersedia dan header memakai Bearer, tanpa tanda kutip di sekitar kunci. |
Kesalahan otorisasi 403 | Berikan cakupan yang diperlukan dengan merotasi kunci integrasi, lalu perbarui klien menggunakan kunci pengganti. |
404 pada URL MCP | Pastikan URL berakhir dengan /api/v1/mcp. Layanan MCP mungkin belum aktif di lingkungan Scoutello ini. |
Kesalahan batas laju 429 | Tunggu hingga waktu reset yang dikembalikan sebelum mencoba lagi. REST dan MCP berbagi kuota integrasi. |
| Alat tidak ada | Periksa cakupan kunci dengan whoami. Alat yang tidak tersedia sengaja tidak ditampilkan saat penemuan. |
Lihat referensi Scoutello API untuk bidang rekaman, paginasi, perilaku batch, dan format respons kesalahan.
Perencanaan proyek yang terhubung
Buat proyek terlebih dahulu, lalu tonggak pencapaian, kemudian tugas dan protokol dengan ID eksternal integrasi yang stabil. Akses ke tonggak baru membutuhkan milestones.read/milestones.write. Berikan members.read untuk mencari anggota yang dapat ditugaskan. Kredensial yang sudah ada tidak otomatis menerima izin tambahan. Setelah rotasi atau pemberian akses, segarkan penemuan alat dan periksa whoami.
Gunakan Customer ID anggota untuk assignedContacts pada proyek dan tonggak; gunakan User ID untuk assignedScoutelloUserIds pada tugas atau ownerScoutelloUserId pada peluang. Referensi tugas dan protokol menerima projectScoutelloId atau projectExternalId, serta pasangan tonggak/peluang yang sesuai. Tautan yang hanya merujuk tonggak menyimpulkan proyeknya; ketidakcocokan menolak item batch. Peserta proyek diproses dengan upsert tambahan; entri yang diabaikan tetap dipertahankan.
Protokol mendukung catatan proyek/tonggak pencapaian tanpa kontak langsung serta status draft/final. Impor pekerjaan yang terhubung ini berlangsung tanpa pemberitahuan dan tidak pernah mengirim komunikasi. Alat daftar menyediakan filter proyek, status, penugasan, dan tanggal jatuh tempo khusus entitas yang sama seperti REST. Teruskan filter yang sama persis, termasuk updatedSince, di setiap halaman kursor. Lihat referensi API untuk kontrak lengkap serta semantik null/diabaikan.
Validasi setiap batch yang bergantung, terapkan, periksa setiap hasil, lalu baca kembali rekaman sebelum menganggap pengisian data selesai. Dry run tidak dapat menyelesaikan induk yang hanya ada di dry run lain. Saat mencoba kembali tautan awal yang ambigu menggunakan scoutelloId, baca terlebih dahulu berdasarkan ID eksternal; ID bootstrap tidak dapat diputar ulang setelah tautan tersedia.
Instruksi agen proyek penjualan
Setiap kontak yang dibuat atau digunakan kembali untuk proyek penjualan harus secara eksplisit merujuk ke proyek tersebut menggunakan projectScoutelloId atau projectExternalId dalam contacts_batch_upsert. Menyebutkan proyek dalam catatan atau ID eksternal bukan berarti menjadi anggota proyek. Penulisan kontak dengan referensi proyek juga memerlukan projects.write. Baca kembali kontak menggunakan contacts.read dan projects.read, lalu verifikasi projectParticipations; pertahankan keanggotaan dan grup yang sudah ada. Kontak umum di luar proyek tidak memerlukan referensi proyek.
Pisahkan perusahaan dan orang terverifikasi sebagai kontak yang berbeda. Tautkan seseorang ke perusahaan menggunakan companyScoutelloId atau companyExternalId, bukan hanya companyName. Perubahan kontak, hubungan perusahaan, dan keanggotaan bersifat atomik untuk setiap item batch; referensi yang tidak valid tidak akan meninggalkan kontak sebagian. Jangan mengarang orang atau menerapkan tag asal-usul.
Siapkan email keluar menggunakan mail_drafts_batch_upsert, jangan pernah sebagai isi protokol. Berikan cakupan mail-drafts.read dan mail-drafts.write yang baru secara eksplisit; persiapan juga memerlukan contacts.read dan projects.write. Kredensial yang sudah ada tidak otomatis menerima izin baru. Gunakan ID eksternal yang stabil, expectedVersion: 0 untuk pembuatan, referensi proyek/kontak yang eksplisit, User ID pemberi persetujuan yang diterima, serta cakupan pengirim organization atau personal yang telah dikonfigurasi. Jangan pernah menebak alamat penerima atau konfigurasi pengirim.
Pertahankan riset di content.notes; hanya content.subject dan content.body yang merupakan salinan untuk dikirim. Pembuatan draf memastikan kontak tersebut merupakan peserta proyek. Pembaruan harus menggunakan versi yang dikembalikan oleh pembacaan terbaru; draf yang telah ditinjau atau dikirim akan menolak pengeditan. Percobaan ulang yang identik mengembalikan draf asli tanpa membuat tinjauan lain. Baca kembali reviewUrl, draftVersion, contentHash, status persetujuan/pengiriman, dan mailScoutelloId yang tersedia kemudian.
Hanya orang yang ditugaskan yang dapat menyetujui dan mengirim melalui layar tinjauan yang ada. Integrasi tidak dapat menyetujui, mengirimkan, atau mengirim, meskipun memiliki akses untuk menulis draf. Pertahankan protokol asli saat mengonversi draf lama dan buat referensi silang ke penggantinya. Kegagalan pengiriman yang tertunda atau ambigu memerlukan penyelidikan, bukan pengiriman ulang secara membabi buta.
Persiapan postingan sosial
Berikan social-channels.read, social-posts.read, social-post-drafts.read, dan
social-post-drafts.write sesuai kebutuhan. members_list (members.read) dapat menemukan
ID pengguna peninjau. Alat sosial hanya ditawarkan jika cakupannya diberikan:
| Cakupan | Alat |
|---|---|
social-channels.read | social_channels_list |
social-posts.read | social_posts_list, social_posts_get |
social-post-drafts.read | social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload |
Baca kemampuan kanal dan riwayat yang dibuat oleh Scoutello, unggah aset, lalu kirim varian kanal lengkap dengan peninjau yang disebutkan namanya. Alat unggah mengembalikan instruksi HTTP PUT: transfer byte file asli di luar MCP, lalu selesaikan unggahan dengan { "assetId": "..." }. Jangan menyematkan file base64 dalam argumen alat.
Gunakan expectedVersion: 0 untuk draf baru dan versi saat ini untuk
revisi yang tertunda. mode: "validate" tidak melakukan penulisan apa pun. Alat tersebut mengembalikan URL tinjauan;
hanya seseorang yang menggunakan dasbor yang dapat menyetujui publikasi atau penjadwalan. Tidak ada
alat MCP untuk menyetujui, memublikasikan, membatalkan, atau menghapus postingan. Poll alat draf/riwayat
untuk mengetahui persetujuan, alasan penolakan, dan hasil pengiriman per kanal. Draf yang telah ditinjau
memerlukan ID eksternal baru untuk proposal berikutnya.
Lihat postingan sosial untuk tinjauan manusia untuk contoh input, batas unggahan, pagination, dan perilaku tinjauan yang terlambat.