Przejdź do głównej zawartości

Integracja MCP

W przypadku organizacji modułowych połączona organizacja musi mieć aktywny moduł CRM oraz zakresy uprawnień wymagane przez integrację. Bazowy interfejs API zwraca kod HTTP 403 wraz z module_not_active, gdy dostęp do CRM jest niedostępny. Przed ponowną próbą przyznaj dostęp do modułu w sekcji Subskrypcja; sama zmiana klucza API nie rozwiąże tego błędu.

Scoutello udostępnia zdalny serwer Model Context Protocol (MCP) zapewniający kontrolowany dostęp do danych organizacji. Korzysta on z tych samych integracji, kluczy API, zakresów uprawnień, kontroli dzierżawy, limitów zapytań i zasad obsługi rekordów co Scoutello REST API.

MCP służy do sytuacji, w których klient AI lub agent ma wykrywać operacje Scoutello i wywoływać je jako narzędzia. REST sprawdzi się, gdy aplikacja potrzebuje standardowych punktów końcowych HTTP lub wygenerowanego klienta OpenAPI. Oba interfejsy korzystają z tego samego bazowego kontraktu danych.

Przed nawiązaniem połączenia​

Administrator organizacji musi utworzyć integrację w sekcji Ustawienia organizacji → Developer/API. Podczas tworzenia lub rotacji klucza:

  1. Wybierz tylko zakresy uprawnień do odczytu i zapisu, których potrzebuje klient MCP.
  2. Zapisz pełny sctl_api_ klucz, gdy zostanie wyświetlony. Scoutello pokazuje go tylko raz.
  3. Przechowuj klucz w sekrecie klienta MCP lub w jego konfiguracji środowiskowej, a nie w systemie kontroli wersji.

Ten sam klucz integracji może służyć do wywoływania REST i MCP. Tworzenie drugiego klucza przeznaczonego wyłącznie dla MCP nie jest wymagane ani zalecane. Klucze sctl_mcp_ nie są akceptowane.

Dane połączenia​

Skonfiguruj klienta za pomocą następujących wartości:

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

Zastąp YOUR_API_KEY zapisanym kluczem integracji. Format konfiguracji zależy od klienta, ale powyższy transport, adres URL i nagłówek HTTP pozostają takie same. Jeśli klient nie może ustawić Authorization, klucz można przesłać zamiast tego w x-api-key. Nie konfiguruj obu nagłówków.

Starszy adres URL https://admin.scoutello.com/api/mcp pozostaje aliasem zapewniającym zgodność. W przypadku nowych połączeń należy używać wersjonowanego punktu końcowego /api/v1/mcp.

Weryfikacja połączenia​

Po nawiązaniu połączenia przez klienta najpierw wywołaj narzędzie whoami. Zwraca ono informacje o bieżącej integracji i organizacji, wygaśnięciu oraz wykorzystaniu poświadczeń, stanie limitów zapytań i przyznanych zakresach uprawnień, bez ujawniania rekordów organizacji.

Jeśli whoami wskazuje nieoczekiwaną organizację lub integrację, odłącz klienta i popraw jego klucz przed wywołaniem kolejnego narzędzia.

Narzędzia i zakresy uprawnień​

Serwer MCP udostępnia wyłącznie narzędzia przyznane przez bieżący klucz. Klient nie może wykrywać ani wywoływać narzędzia do zapisu, korzystając wyłącznie z odpowiadającego mu zakresu odczytu.

Zakres APINarzędzia 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 (w tym operacje upsert uczestników)
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 (wyłącznie do przygotowania do weryfikacji przez człowieka)
tags.readtags_list

whoami jest zawsze dostępne dla uwierzytelnionego połączenia. Dane wejściowe i wyniki narzędzi są zgodne z tymi samymi schematami i obiektami odpowiedzi co powiązane operacje REST.

contacts_list przyjmuje ograniczone search w polach imienia, nazwiska i nazwy firmy, type, status oraz tagIds (tablicę od 1 do 50 identyfikatorów, dopasowującą dowolny wybrany tag). Wszystkie tokeny wyszukiwania muszą pasować do pola nazwy; wszystkie filtry są łączone operatorem AND. Stosuj te filtry przy każdej stronie wyników oznaczonej kursorem. Na przykład { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } wyszukuje pasujące istniejące konta bez skanowania całego zbioru.

Kontakty CRM niebędące członkami, powiązane z loginem Scoutello, można odczytywać i wskazywać, natomiast pola członkostwa i konta pozostają ukryte, a edycja kontaktów jest chroniona. Operacja upsert oparta wyłącznie na zewnętrznym powiązaniu może zarejestrować kontakt dostępny do odczytu za pomocą externalId, jego scoutelloId oraz opcjonalnego externalUpdatedAt; należy pominąć wszystkie pola CRM. Przy kolejnych ponowieniach i aktualizacjach metadanych pomiń scoutelloId. Zobacz zasady dotyczące granic kontaktów i powiązań.

Bezpieczne operacje zapisu​

Narzędzia wsadowego upsertu mogą natychmiast zmieniać dane Scoutello. Dla tej samej integracji i identyfikatorów zewnętrznych są idempotentne, ale przed zastosowaniem zmian należy nadal sprawdzić właściwy zasób, organizację i zakres.

Ustaw mode na validate, aby przeprowadzić dopasowanie i walidację bez zapisywania danych. Po sprawdzeniu wyników powtórz wywołanie z mode: "apply", aby zaakceptować prawidłowe rekordy. MCP nie udostępnia operacji usuwania.

Wstrzymanie integracji odrzuca żądania REST i MCP korzystające z jej kluczy. Rotacja zastępuje jej dane uwierzytelniające, a unieważnienie trwale wyłącza wszystkie dane uwierzytelniające należące do integracji.

Rozwiązywanie problemów​

WynikCo sprawdzić
Błąd uwierzytelniania 401Sprawdź, czy podano kompletny klucz, a nagłówek używa Bearer bez cudzysłowów wokół klucza.
Błąd autoryzacji 403Nadaj wymagany zakres, wykonując rotację klucza integracji, a następnie zaktualizuj klienta przy użyciu zastępczego klucza.
404 pod adresem MCPSprawdź, czy adres kończy się na /api/v1/mcp. Usługa MCP może nie być jeszcze włączona w tym środowisku Scoutello.
Błąd limitu żądań 429Przed ponowieniem próby zaczekaj do zwróconego czasu resetu. REST i MCP korzystają z tego samego limitu integracji.
Brak narzędziaSprawdź zakresy klucza za pomocą whoami; niedostępne narzędzia są celowo pomijane podczas wykrywania.

Informacje o polach rekordów, paginacji, działaniu operacji wsadowych i kopertach błędów znajdują się w dokumentacji API Scoutello.

Planowanie projektów połączonych​

Utwórz projekt, następnie jego kamienie milowe, a potem zadania i protokoły, używając stałych zewnętrznych identyfikatorów integracji. Dostęp do nowych kamieni milowych wymaga milestones.read/milestones.write; nadaj members.read, aby wyszukiwać członków możliwych do przypisania. Istniejące dane uwierzytelniające nie otrzymują automatycznie szerszych uprawnień. Po rotacji lub nadaniu dostępu odśwież wykrywanie narzędzi i sprawdź whoami.

W przypadku assignedContacts projektu lub kamienia milowego używaj identyfikatorów Customer członków, a w przypadku assignedScoutelloUserIds zadania lub ownerScoutelloUserId okazji — identyfikatorów User. Odwołania do zadań i protokołów przyjmują projectScoutelloId lub projectExternalId, a także odpowiadające im pary kamienia milowego i okazji. Linki zawierające wyłącznie kamień milowy wskazują projekt automatycznie; niezgodności powodują odrzucenie elementu wsadowego. Uczestnicy projektu są dodawani lub aktualizowani bez usuwania pominiętych wpisów.

Protokoły obsługują bezkontaktowe notatki projektu lub kamienia milowego oraz status draft/final. Import tych połączonych danych odbywa się bez powiadomień i nigdy nie wysyła komunikacji. Narzędzia listowania udostępniają te same właściwe dla encji filtry projektu, statusu, przypisania i terminu co REST. Przekazuj dokładne filtry, w tym updatedSince, przez każdą stronę kursora. Pełny kontrakt oraz semantykę wartości null i pominiętych pól opisano w dokumentacji API.

Waliduj każdą zależną operację wsadową, zastosuj ją, sprawdź każdy wynik i odczytaj rekordy ponownie, zanim uznasz uzupełnienie danych za zakończone. Tryb testowy nie może rozwiązać zależności do elementów, które istnieją wyłącznie w innym trybie testowym. Przy ponawianiu niejednoznacznego początkowego linku za pomocą scoutelloId najpierw odczytaj dane po identyfikatorze zewnętrznym; identyfikatorów rozruchowych nie można ponownie wykorzystać po utworzeniu linku.

Instrukcje agenta ds. projektów sprzedażowych​

Każdy kontakt utworzony lub ponownie wykorzystany na potrzeby projektu sprzedażowego musi jawnie wskazywać ten projekt za pomocą projectScoutelloId lub projectExternalId w contacts_batch_upsert. Wzmianka o projekcie w notatkach lub zewnętrznym identyfikatorze nie oznacza członkostwa. Zapisy kontaktów z odwołaniami do projektu wymagają również projects.write. Odczytaj kontakt ponownie za pomocą contacts.read i projects.read, a następnie sprawdź projectParticipations; zachowaj istniejące członkostwa i grupy. Ogólne kontakty spoza projektu nie wymagają odwołania do projektu.

Przechowuj firmy i zweryfikowane osoby jako osobne kontakty. Połącz osobę z firmą za pomocą companyScoutelloId lub companyExternalId, a nie wyłącznie companyName. Zmiany kontaktu, relacji z firmą i członkostwa są atomowe dla każdego elementu wsadowego; nieprawidłowe odwołania nie pozostawiają częściowo utworzonego kontaktu. Nie wymyślaj osób ani nie stosuj tagów pochodzenia.

Przygotowuj wychodzące wiadomości e-mail za pomocą mail_drafts_batch_upsert, nigdy jako treść protokołów. Jawnie nadaj nowe zakresy mail-drafts.read i mail-drafts.write; przygotowanie wymaga również contacts.read i projects.write. Istniejące dane uwierzytelniające nie otrzymują automatycznie nowych uprawnień. Użyj stałego identyfikatora zewnętrznego, expectedVersion: 0 podczas tworzenia, jawnych odwołań do projektu i kontaktu, identyfikatora User zatwierdzonej osoby zatwierdzającej oraz skonfigurowanego zakresu nadawcy organization lub personal. Nigdy nie zgaduj adresu odbiorcy ani konfiguracji nadawcy.

Przechowuj materiały badawcze w content.notes; wyłącznie content.subject i content.body zawierają treść wychodzącą. Utworzenie wersji roboczej zapewnia, że kontakt jest uczestnikiem projektu. Aktualizacje muszą używać wersji zwróconej podczas najnowszego odczytu; edycje sprawdzonych lub wysłanych wersji roboczych są odrzucane. Identyczne ponowienia zwracają pierwotną wersję roboczą bez tworzenia kolejnej do sprawdzenia. Odczytaj ponownie reviewUrl, draftVersion, contentHash, status zatwierdzenia lub wysyłki oraz ostateczny mailScoutelloId.

Tylko przypisana osoba może zatwierdzać i wysyłać za pośrednictwem istniejącego ekranu weryfikacji. Integracje nie mogą zatwierdzać, przekazywać do wysyłki ani wysyłać wiadomości, nawet jeśli mają dostęp do zapisu wersji roboczych. Zachowaj pierwotne protokoły podczas konwertowania starych wersji roboczych i dodaj wzajemne odwołania do zamienników. Błędy dostarczenia związane z kolejką lub niejednoznaczne wymagają zbadania, nigdy bezrefleksyjnego ponownego wysłania.

Przygotowanie postów w mediach społecznościowych​

W razie potrzeby przyznaj social-channels.read, social-posts.read, social-post-drafts.read oraz social-post-drafts.write. members_list (members.read) umożliwia wykrywanie identyfikatorów użytkowników recenzentów. Narzędzia społecznościowe są reklamowane tylko wtedy, gdy przyznano odpowiedni zakres uprawnień:

ZakresNarzędzia
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

Odczytaj możliwości kanałów i historię utworzoną przez Scoutello, prześlij zasoby, a następnie prześlij kompletne warianty kanałów wraz ze wskazanym recenzentem. Narzędzia przesyłania zwracają instrukcje HTTP PUT: prześlij oryginalne bajty pliku poza MCP, a następnie sfinalizuj przesyłanie za pomocą { "assetId": "..." }. Nie umieszczaj plików zakodowanych w formacie base64 w argumentach narzędzi.

Użyj expectedVersion: 0 w przypadku nowych wersji roboczych, a bieżącej wersji w przypadku oczekujących zmian. mode: "validate" nie wykonuje żadnych zapisów. Narzędzie zwraca adres URL recenzji; tylko osoba korzystająca z pulpitu może zatwierdzić publikację lub zaplanowanie publikacji. Nie istnieje narzędzie MCP umożliwiające zatwierdzanie, publikowanie, anulowanie ani usuwanie posta. Odpytywanie narzędzi wersji roboczych i historii pozwala sprawdzać zatwierdzenie, powody odrzucenia oraz wyniki dostarczenia dla poszczególnych kanałów. Zrecenzowane wersje robocze wymagają nowego zewnętrznego identyfikatora przy składaniu kolejnych propozycji.

Zobacz sekcję posty społecznościowe do weryfikacji przez człowieka, aby poznać przykłady danych wejściowych, limity przesyłania, paginację oraz sposób obsługi opóźnionych recenzji.