Ana içeriğe geç

MCP entegrasyonu

Modüler kuruluşlarda, bağlı kuruluşta entegrasyonun gerektirdiği kapsamların yanı sıra etkin bir CRM modülü de bulunmalıdır. CRM erişimi kullanılamadığında temel API, module_not_active ile HTTP 403 döndürür. Yeniden denemeden önce modül erişimini Subscription bölümünden çözümleyin; yalnızca API anahtarını değiştirmek bu hatayı gidermez.

Scoutello, kuruluş verilerine kontrollü erişim için uzak bir Model Context Protocol (MCP) sunucusu sağlar. Bu sunucu, Scoutello REST API ile aynı entegrasyonları, API anahtarlarını, kapsamları, kiracı kontrollerini, hız sınırlarını ve kayıt davranışını kullanır.

Bir yapay zekâ istemcisi veya aracısının Scoutello işlemlerini araç olarak keşfetmesi ve çağırması gerekiyorsa MCP’yi kullanın. Bir uygulamanın standart HTTP uç noktalarına veya oluşturulmuş bir OpenAPI istemcisine ihtiyacı varsa REST’i kullanın. Her iki arayüz de aynı temel veri sözleşmesini kullanır.

Bağlanmadan önce​

Bir kuruluş yöneticisinin Organization settings → Developer/API bölümünde bir entegrasyon oluşturması gerekir. Anahtar oluştururken veya yenilerken:

  1. MCP istemcisinin ihtiyaç duyduğu yalnızca okuma ve yazma kapsamlarını seçin.
  2. Gösterildiğinde sctl_api_ anahtarının tamamını kaydedin. Scoutello bu anahtarı yalnızca bir kez gösterir.
  3. Anahtarı kaynak kodu deposunda değil, MCP istemcisinin gizli bilgi veya ortam yapılandırmasında saklayın.

Aynı entegrasyon anahtarı REST ve MCP çağrıları yapabilir. MCP’ye özel ikinci bir anahtar oluşturmak gerekli olmadığı gibi önerilmez. Önceki sctl_mcp_ anahtarları kabul edilmez.

Bağlantı değerleri​

İstemciyi şu değerlerle yapılandırın:

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

YOUR_API_KEY yerine kaydedilmiş entegrasyon anahtarını yazın. İstemci yapılandırma biçimleri farklılık gösterir; ancak yukarıdaki aktarım, URL ve HTTP üst bilgisi aynı kalır. Bir istemci Authorization ayarlayamıyorsa anahtarı bunun yerine x-api-key içinde gönderebilir. Her iki üst bilgiyi birlikte yapılandırmayın.

Eski https://admin.scoutello.com/api/mcp URL’si uyumluluk takma adı olarak kullanılmaya devam eder. Yeni bağlantılarda sürümlü /api/v1/mcp uç noktası kullanılmalıdır.

Bağlantıyı doğrulama​

İstemci bağlandıktan sonra önce whoami aracını çağırın. Bu araç, kuruluş kayıtlarını açığa çıkarmadan geçerli entegrasyonu ve kuruluşu, kimlik bilgilerinin sona erme ve kullanım bilgilerini, hız sınırı durumunu ve verilen kapsamları döndürür.

whoami beklenmeyen bir kuruluş veya entegrasyon tanımlıyorsa istemcinin bağlantısını kesin ve başka bir araç çağırmadan önce anahtarını düzeltin.

Araçlar ve kapsamlar​

MCP sunucusu yalnızca geçerli anahtar tarafından verilen araçları tanıtır. İstemci, yalnızca karşılık gelen okuma kapsamını kullanarak bir yazma aracını keşfedemez veya çağıramaz.

API kapsamıMCP araçları
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 (katılımcı eklemeleri dahil)
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 (yalnızca insan incelemesine hazırlık için)
tags.readtags_list

whoami, kimliği doğrulanmış bir bağlantı için her zaman kullanılabilir. Araç girdileri ve sonuçları, bağlantılı REST işlemleriyle aynı şemaları ve yanıt zarflarını izler.

contacts_list, adlar/soyadlar/şirket adları, type, status ve tagIds (seçilen etiketlerden herhangi biriyle eşleşen 1–50 kimlikten oluşan bir dizi) üzerinde sınırlandırılmış search kabul eder. Tüm arama belirteçleri bir ad alanıyla eşleşmelidir; tüm filtreler AND ile birleştirilir. Bu filtreleri her imleç sayfasında koruyun. Örneğin { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] }, envanterin tamamını taramadan eşleşen mevcut hesapları bulur.

Scoutello oturum açma bilgilerine bağlı olmayan CRM kişileri okunabilir ve referans verilebilir; ancak üyelik/hesap alanları gizli kalır ve kişi düzenlemeleri koruma altında tutulur. Yalnızca dış bağlantı içeren bir upsert işlemi, externalId, bunun scoutelloId değeri ve isteğe bağlı externalUpdatedAt kullanılarak okunabilir bir kişi kaydı oluşturabilir; tüm CRM alanlarını hariç tutun. Sonraki yeniden denemelerde veya meta veri güncellemelerinde scoutelloId alanını hariç tutun. Kişi sınırı ve bağlama kurallarına bakın.

Güvenli yazma​

Toplu upsert araçları, Scoutello verilerini anında değiştirebilir. Aynı entegrasyon ve harici kimlikler için idempotent çalışırlar; ancak çağrıyı yapan taraflar değişiklikleri uygulamadan önce hedef kaynağı, kuruluşu ve kapsamı yine de gözden geçirmelidir.

Yazma işlemi gerçekleştirmeden eşleştirme ve doğrulama yapmak için mode değerini validate olarak ayarlayın. Sonuçları inceledikten sonra geçerli kayıtları kabul etmek için çağrıyı mode: "apply" ile tekrarlayın. MCP, silme işlemlerini sunmaz.

Bir entegrasyonu duraklatmak, anahtarlarını kullanan REST ve MCP isteklerinin her ikisini de reddeder. Anahtarı döndürmek kimlik bilgisini yenisiyle değiştirir; iptal etmek ise entegrasyona ait tüm kimlik bilgilerini kalıcı olarak devre dışı bırakır.

Sorun giderme​

SonuçKontrol edilmesi gereken
401 kimlik doğrulama hatasıAnahtarın tamamının mevcut olduğunu ve üstbilgide Bearer kullanıldığını, anahtarın çevresinde tırnak bulunmadığını doğrulayın.
403 yetkilendirme hatasıEntegrasyon anahtarını döndürerek gerekli kapsamı verin, ardından istemciyi yeni anahtarla güncelleyin.
MCP URL'sinde 404URL'nin /api/v1/mcp ile bittiğini doğrulayın. MCP hizmeti henüz bu Scoutello ortamında etkinleştirilmemiş olabilir.
429 hız sınırı hatasıYeniden denemeden önce döndürülen sıfırlama zamanına kadar bekleyin. REST ve MCP aynı entegrasyon kotasını kullanır.
Araç eksikAnahtarın kapsamlarını whoami ile kontrol edin; kullanılamayan araçlar keşifte kasıtlı olarak gösterilmez.

Kayıt alanları, sayfalama, toplu işlem davranışı ve hata zarfları için Scoutello API referansına devam edin.

Bağlı proje planlama​

Önce bir proje, ardından sabit entegrasyon harici kimliklerini kullanarak kilometre taşları, görevler ve protokoller oluşturun. Yeni kilometre taşı erişimi milestones.read/milestones.write gerektirir; atanabilir üyeleri aramak için members.read kapsamını verin. Mevcut kimlik bilgilerinin kapsamı otomatik olarak genişletilmez. Erişimi döndürdükten veya verdikten sonra araç keşfini yenileyin ve whoami değerini inceleyin.

Proje/kilometre taşı assignedContacts için üye Müşteri Kimliklerini, görev assignedScoutelloUserIds veya fırsat ownerScoutelloUserId için Kullanıcı Kimliklerini kullanın. Görev/protokol referansları projectScoutelloId veya projectExternalId değerlerini ve bunlara karşılık gelen kilometre taşı/fırsat çiftlerini kabul eder. Yalnızca kilometre taşı bağlantıları projeyi belirler; uyuşmazlıklar toplu işlem öğesinin reddedilmesine neden olur. Proje katılımcıları eklemeli upsert işlemleridir ve belirtilmeyen kayıtları korur.

Protokoller, iletişim içermeyen proje/kilometre taşı notlarını ve draft/final durumunu destekler. Bu bağlı çalışmaların içe aktarılması sessizce gerçekleştirilir ve hiçbir zaman iletişim göndermez. Listeleme araçları, REST'teki varlığa özgü aynı proje, durum, atama ve son tarih filtrelerini sunar. updatedSince dahil olmak üzere tam filtreleri her imleç sayfasında koruyarak iletin. Eksiksiz sözleşme ile null/belirtilmemiş semantiği için API referansına bakın.

Her bağımlı toplu işlemi doğrulayın, uygulayın, her sonucu inceleyin ve kayıtları tekrar okuyarak verilerin tamamlandığını kabul edin. Kuru çalıştırma, yalnızca başka bir kuru çalıştırmada mevcut olan üst kayıtları çözümleyemez. scoutelloId kullanarak belirsiz bir ilk bağlantıyı yeniden denerken önce harici kimliğe göre okuyun; bağlantı oluşturulduktan sonra önyükleme kimlikleri yeniden oynatılamaz.

Satış projesi aracı talimatları​

Bir satış projesi için oluşturulan veya yeniden kullanılan her kişi, contacts_batch_upsert içinde projectScoutelloId veya projectExternalId kullanılarak o projeye açıkça bağlanmalıdır. Notlarda veya harici kimlikte bir projeden söz edilmesi üyelik anlamına gelmez. Proje referansları içeren kişi yazma işlemleri ayrıca projects.write gerektirir. Kişiyi contacts.read ve projects.read ile tekrar okuyun ve projectParticipations değerini doğrulayın; mevcut üyelikleri ve grupları koruyun. Proje dışındaki genel kişiler için proje referansı gerekmez.

Şirketleri ve doğrulanmış kişileri ayrı kişiler olarak tutun. Bir kişiyi şirkete yalnızca companyName kullanarak değil, companyScoutelloId veya companyExternalId ile bağlayın. Kişi, şirket ilişkisi ve üyelik değişiklikleri her toplu işlem öğesi için atomiktir; geçersiz referanslar kısmen oluşturulmuş kişi bırakmaz. Kişi uydurmayın ve kaynak gösterimi etiketleri uygulamayın.

Giden e-postaları protokol gövdesi olarak değil, mail_drafts_batch_upsert ile hazırlayın. Yeni mail-drafts.read ve mail-drafts.write kapsamlarını açıkça verin; hazırlama işlemi ayrıca contacts.read ve projects.write gerektirir. Mevcut kimlik bilgilerine yeni izinler otomatik olarak verilmez. Sabit bir harici kimlik, oluşturma için expectedVersion: 0, açık proje/kişi referansları, onaylanmış bir onaylayanın Kullanıcı Kimliği ve yapılandırılmış bir organization veya personal gönderen kapsamı kullanın. Alıcı adresini veya gönderen yapılandırmasını asla tahmin etmeyin.

Araştırmayı content.notes içinde tutun; yalnızca content.subject ve content.body giden metindir. Taslak oluşturma, kişinin proje katılımcısı olmasını sağlar. Güncellemelerde son okumada döndürülen sürüm kullanılmalıdır; incelenmiş veya gönderilmiş taslaklar düzenleme işlemlerini reddeder. Aynı yeniden denemeler, başka bir inceleme oluşturmadan özgün taslağı döndürür. reviewUrl, draftVersion, contentHash değerlerini, onaylama/gönderme durumunu ve nihai mailScoutelloId değerini tekrar okuyun.

Yalnızca atanan kişi mevcut inceleme ekranı üzerinden onaylayabilir ve gönderebilir. Entegrasyonlar, taslak yazma erişimine sahip olsalar bile onaylayamaz, dağıtamaz veya gönderemez. Eski taslakları dönüştürürken özgün protokolleri koruyun ve yenileriyle çapraz referans verin. Kuyruğa alınmış veya belirsiz teslimat hataları araştırılmalıdır; körlemesine yeniden gönderim yapılmamalıdır.

Sosyal medya gönderisi hazırlama​

social-channels.read, social-posts.read, social-post-drafts.read ve social-post-drafts.write gerektiği şekilde verin. members_list (members.read), inceleyen kişilerin kullanıcı kimliklerini keşfedebilir. Sosyal araçlar yalnızca kapsamları verildiğinde gösterilir:

KapsamAraçlar
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

Kanal yeteneklerini ve Scoutello tarafından oluşturulan geçmişi okuyun, varlıkları yükleyin, ardından kanal varyantlarının tamamını adı belirtilmiş bir inceleyen kişiye gönderin. Yükleme araçları HTTP PUT talimatları döndürür: orijinal dosya baytlarını MCP dışında aktarın, ardından yüklemeyi { "assetId": "..." } ile tamamlayın. Araç bağımsız değişkenlerine base64 dosyaları yerleştirmeyin.

Yeni taslaklar için expectedVersion: 0, bekleyen düzeltmeler için mevcut sürümü kullanın. mode: "validate" hiçbir yazma işlemi gerçekleştirmez. Araç, inceleme URL'sini döndürür; yayınlamayı veya planlamayı yalnızca gösterge tablosunu kullanan bir kişi onaylayabilir. Bir gönderiyi onaylamak, yayınlamak, iptal etmek veya silmek için MCP aracı yoktur. Onay, ret nedenleri ve kanal başına teslim sonuçları için taslak/geçmiş araçlarını yoklayın. İncelenen taslaklar, sonraki öneriler için yeni bir harici kimlik gerektirir.

Girdi örnekleri, yükleme sınırları, sayfalama ve gecikmiş inceleme davranışı için insan incelemesine sunulan sosyal gönderiler sayfasına bakın.