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:
- Wybierz tylko zakresy uprawnień do odczytu i zapisu, których potrzebuje klient MCP.
- Zapisz pełny
sctl_api_klucz, gdy zostanie wyświetlony. Scoutello pokazuje go tylko raz. - 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 API | Narzędzia 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 (w tym operacje upsert uczestników) |
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 (wyłącznie do przygotowania do weryfikacji przez człowieka) |
tags.read | tags_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
| Wynik | Co sprawdzić |
|---|---|
Błąd uwierzytelniania 401 | Sprawdź, czy podano kompletny klucz, a nagłówek używa Bearer bez cudzysłowów wokół klucza. |
Błąd autoryzacji 403 | Nadaj wymagany zakres, wykonując rotację klucza integracji, a następnie zaktualizuj klienta przy użyciu zastępczego klucza. |
404 pod adresem MCP | Sprawdź, 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ń 429 | Przed ponowieniem próby zaczekaj do zwróconego czasu resetu. REST i MCP korzystają z tego samego limitu integracji. |
| Brak narzędzia | Sprawdź 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ń:
| Zakres | Narzędzia |
|---|---|
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 |
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.