Lewati ke konten utama

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:

  1. Pilih hanya cakupan baca dan tulis yang diperlukan klien MCP.
  2. Simpan kunci sctl_api_ lengkap saat ditampilkan. Scoutello hanya menampilkannya satu kali.
  3. 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 APIAlat MCP
contacts.readcontacts_list, contacts_get, contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list, tasks_get, tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list, protocols_get, protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list, opportunities_get, opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list, projects_get, projects_get_by_external_id
projects.writeprojects_batch_upsert (termasuk upsert peserta)
milestones.readmilestones_list, milestones_get, milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list, events_get, events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list, mails_get
mail-drafts.readmail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert (hanya untuk persiapan peninjauan oleh manusia)
tags.readtags_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​

HasilYang perlu diperiksa
Kesalahan autentikasi 401Pastikan kunci lengkap tersedia dan header memakai Bearer, tanpa tanda kutip di sekitar kunci.
Kesalahan otorisasi 403Berikan cakupan yang diperlukan dengan merotasi kunci integrasi, lalu perbarui klien menggunakan kunci pengganti.
404 pada URL MCPPastikan URL berakhir dengan /api/v1/mcp. Layanan MCP mungkin belum aktif di lingkungan Scoutello ini.
Kesalahan batas laju 429Tunggu hingga waktu reset yang dikembalikan sebelum mencoba lagi. REST dan MCP berbagi kuota integrasi.
Alat tidak adaPeriksa 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:

CakupanAlat
social-channels.readsocial_channels_list
social-posts.readsocial_posts_list, social_posts_get
social-post-drafts.readsocial_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id
social-post-drafts.writesocial_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.