MCP-integráció
Moduláris szervezeteknél a csatlakoztatott szervezetnek aktív CRM-modullal és az integráció által megkövetelt hatókörökkel is rendelkeznie kell. Az alapul szolgáló API HTTP 403-as hibát ad vissza a következővel: module_not_active, ha a CRM-hozzáférés nem érhető el. Az újrapróbálkozás előtt oldja fel a modulhoz való hozzáférést a Subscription menüpontban; önmagában az API-kulcs módosítása nem oldja meg ezt a hibát.
A Scoutello távoli Model Context Protocol (MCP) szervert biztosít a szervezeti adatok szabályozott eléréséhez. Ugyanazokat az integrációkat, API-kulcsokat, hatóköröket, bérlő-ellenőrzéseket, sebességkorlátozásokat és rekordkezelési szabályokat használja, mint a Scoutello REST API.
Az MCP akkor használható, ha egy AI-kliensnek vagy -ügynöknek fel kell fedeznie és eszközként meg kell hívnia a Scoutello-műveleteket. A REST akkor használható, ha egy alkalmazás hagyományos HTTP-végpontokat vagy generált OpenAPI-klienst igényel. Mindkét felület ugyanazt az alapul szolgáló adatszerződést használja.
Csatlakozás előtt
A szervezet adminisztrátorának integrációt kell létrehoznia a Szervezeti beállítások → Developer/API menüpontban. A kulcs létrehozásakor vagy cseréjekor:
- Csak azokat az olvasási és írási hatóköröket válassza ki, amelyekre az MCP-kliensnek szüksége van.
- Mentse el a teljes
sctl_api_kulcsot, amikor megjelenik. A Scoutello csak egyszer jeleníti meg. - A kulcsot az MCP-kliens titkos vagy környezeti konfigurációjában tárolja, ne a forráskódban.
Ugyanaz az integrációs kulcs használható a REST- és az MCP-hívásokhoz. Külön, MCP-hez kötött kulcs létrehozása nem szükséges és nem ajánlott. A korábbi sctl_mcp_ kulcsokat a rendszer nem fogadja el.
Csatlakozási értékek
Állítsa be a klienst a következő értékekkel:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
A YOUR_API_KEY helyére illessze be a mentett integrációs kulcsot. A klienskonfiguráció formátuma eltérhet, de a fenti transzport, URL és HTTP-fejléc változatlan marad. Ha a kliens nem tudja beállítani a Authorization fejlécet, a kulcsot helyette a x-api-key fejlécben küldheti. Ne állítsa be mindkét fejlécet.
A régi https://admin.scoutello.com/api/mcp URL továbbra is kompatibilitási alias marad. Az új csatlakozásokhoz a verziózott /api/v1/mcp végpontot használja.
A kapcsolat ellenőrzése
A kliens csatlakozása után először a whoami eszközt hívja meg. Ez visszaadja az aktuális integrációt és szervezetet, a hitelesítő adatok lejárati és használati információit, a sebességkorlátozás állapotát, valamint a megadott hatóköröket, miközben nem tesz közzé szervezeti rekordokat.
Ha a whoami váratlan szervezetet vagy integrációt azonosít, bontsa a kliens kapcsolatát, és másik eszköz meghívása előtt javítsa ki a kulcsot.
Eszközök és hatókörök
Az MCP-szerver csak az aktuális kulcs által engedélyezett eszközöket hirdeti meg. A kliens nem fedezhet fel és nem hívhat meg írási eszközt, ha csak a megfelelő olvasási hatókörrel rendelkezik.
| API-hatókör | MCP-eszközök |
|---|---|
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 (beleértve a résztvevők upsertelését) |
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 (csak emberi ellenőrzésre előkészítve) |
tags.read | tags_list |
A whoami minden hitelesített kapcsolat számára elérhető. Az eszközbemenetek és -eredmények ugyanazokat a sémákat és válaszburkokat követik, mint a hozzájuk kapcsolódó REST-műveletek.
A contacts_list korlátozott számú search értéket fogad az utó- és keresztnév, a cégnév, a type, a status és a tagIds mezőkhöz (1–50 azonosítót tartalmazó tömb, amely megfelel bármely kiválasztott címkének). Minden keresési tokennek illeszkednie kell egy névmezőre; minden szűrő AND kapcsolatban áll egymással. Ezeket a szűrőket minden kurzoroldalon vigye tovább. A { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } például a teljes készlet átvizsgálása nélkül keresi meg a megfelelő, már létező fiókokat.
A Scoutello-bejelentkezéshez kapcsolt, nem tag CRM-kapcsolatok olvashatók és hivatkozhatók, miközben a tagsági és fiókmezők rejtve maradnak, a kapcsolattartói módosítások pedig védettek. Egy kizárólag külső hivatkozást tartalmazó upsert olvasható kapcsolatot regisztrálhat a externalId, annak scoutelloId értéke és egy opcionális externalUpdatedAt használatával; hagyja ki az összes CRM-mezőt. A későbbi újrapróbálkozások és metaadat-frissítések során hagyja ki a scoutelloId mezőt. Lásd a kapcsolati korlátozásokat és összekapcsolási szabályokat.
Biztonságos írás
A Batch-upsert eszközök azonnal módosíthatják a Scoutello adatait. Ugyanazon integráció és külső azonosítók esetén idempotensek, de a hívóknak a módosítások alkalmazása előtt így is ellenőrizniük kell a kívánt erőforrást, szervezetet és hatókört.
Állítsa a mode értékét validate értékre az egyezés és az ellenőrzés írási művelet nélküli futtatásához. Az eredmények ellenőrzése után ismételje meg a hívást mode: "apply" értékkel az érvényes rekordok elfogadásához. Az MCP nem biztosít törlési műveleteket.
Egy integráció szüneteltetése elutasítja a kulcsaival küldött REST- és MCP-kéréseket. A kulcs rotálása lecseréli a hozzá tartozó hitelesítő adatot, a visszavonás pedig véglegesen letiltja az integrációhoz tartozó összes hitelesítő adatot.
Hibaelhárítás
| Eredmény | Ellenőrizendő |
|---|---|
401 hitelesítési hiba | Ellenőrizze, hogy a teljes kulcs szerepel-e, és a fejléc a Bearer értéket használja-e, valamint hogy a kulcs körül nincsenek idézőjelek. |
403 engedélyezési hiba | Adja meg a szükséges hatókört az integrációs kulcs rotálásával, majd frissítse a klienst a cserélt kulccsal. |
404 az MCP URL-címen | Ellenőrizze, hogy az URL /api/v1/mcp értékre végződik-e. Előfordulhat, hogy az MCP-szolgáltatás még nincs engedélyezve az adott Scoutello-környezetben. |
429 sebességkorlátozási hiba | Az újrapróbálkozással várja meg a válaszban megadott visszaállítási időt. A REST és az MCP ugyanazt az integrációs kvótát használja. |
| Hiányzó eszköz | Ellenőrizze a kulcs hatóköreit a whoami használatával; a nem elérhető eszközök szándékosan kimaradnak a felderítésből. |
A rekordmezőkkel, a lapozással, a kötegelt működéssel és a hibaobjektumokkal kapcsolatos részletekért tekintse meg a Scoutello API-referenciát.
Összekapcsolt projekttervezés
Hozzon létre egy projektet, majd a mérföldköveit, végül pedig a feladatokat és protokollokat stabil integrációs külső azonosítók használatával. Az új mérföldkő-hozzáféréshez milestones.read/milestones.write szükséges; az members.read hatókörrel kereshetők ki a hozzárendelhető tagok. A meglévő hitelesítő adatok hatóköre nem bővül automatikusan. A hozzáférés rotálása vagy megadása után frissítse az eszközfelderítést, és ellenőrizze a whoami értéket.
A projekt- és mérföldkő- assignedContacts értékekhez a tagok Customer ID-ját, a feladat assignedScoutelloUserIds vagy a lehetőség ownerScoutelloUserId értékéhez pedig a User ID-kat használja. A feladat- és protokollhivatkozások elfogadják a projectScoutelloId vagy projectExternalId értéket, valamint a megfelelő mérföldkő-/lehetőségpárokat. A csak mérföldkőre mutató hivatkozásokból a projekt kikövetkeztethető; az eltérések miatt a kötegelem elutasításra kerül. A projektrésztvevők hozzáadódó upsert műveletekkel kezelhetők, a kihagyott bejegyzések megmaradnak.
A protokollok támogatják a kapcsolattartó nélküli projekt-/mérföldkőjegyzeteket, valamint az draft/final állapotot. Az összekapcsolt munka importálása csendes, és soha nem küld kommunikációt. A listázó eszközök ugyanazokat az entitásspecifikus projekt-, állapot-, hozzárendelési és határidőszűrőket teszik elérhetővé, mint a REST. Pontosan ugyanazokat a szűrőket, köztük a updatedSince értéket is, vigye tovább minden kurzoroldalon. A teljes szerződésért, valamint a null- és kihagyási szemantikáért tekintse meg az API-referenciát.
Ellenőrizzen minden függő köteget, alkalmazza, vizsgálja meg minden eredményét, majd olvassa vissza a rekordokat, mielőtt a feltöltést befejezettnek tekintené. A próbaüzem nem tudja feloldani azokat a szülőket, amelyek csak egy másik próbaüzemben léteznek. Ha egy kezdeti, bizonytalan hivatkozást próbál újra scoutelloId használatával, először külső azonosító alapján olvassa be; a bootstrap-azonosítók nem játszhatók újra a hivatkozás létrejötte után.
Értékesítési projektekhez tartozó ügynöki utasítások
Minden értékesítési projekthez létrehozott vagy újrahasznált kapcsolattartónak kifejezetten hivatkoznia kell a projektre a projectScoutelloId vagy projectExternalId használatával a contacts_batch_upsert mezőben. A projekt említése a jegyzetekben vagy egy külső azonosítóban nem jelent tagságot. A projekthivatkozásokat tartalmazó kapcsolattartó-műveletekhez a projects.write is szükséges. Olvassa vissza a kapcsolattartót a contacts.read és projects.read használatával, ellenőrizze a projectParticipations értéket, és őrizze meg a meglévő tagságokat és csoportokat. Az általános, projekten kívüli kapcsolattartókhoz nem szükséges projekthivatkozás.
A vállalatokat és az ellenőrzött személyeket külön kapcsolattartóként kezelje. A személyt a vállalathoz a companyScoutelloId vagy companyExternalId használatával kapcsolja, ne csak a companyName segítségével. A kapcsolattartó-, vállalati kapcsolat- és tagsági módosítások kötegenként, elemenként atomiak; az érvénytelen hivatkozások nem hagynak részben létrehozott kapcsolattartót. Ne találjon ki személyeket, és ne alkalmazzon származási címkéket.
A kimenő e-maileket a mail_drafts_batch_upsert használatával készítse elő, soha ne protokolltörzsként. Kifejezetten adja meg az új mail-drafts.read és mail-drafts.write hatóköröket; az előkészítéshez ezenfelül a contacts.read és projects.write is szükséges. A meglévő hitelesítő adatok nem kapnak automatikusan új jogosultságokat. Használjon stabil külső azonosítót, a létrehozáshoz expectedVersion: 0 értéket, kifejezett projekt- és kapcsolattartó-hivatkozásokat, egy elfogadott jóváhagyó User ID-ját, valamint egy beállított organization vagy personal feladói hatókört. Soha ne találja ki a címzett címét vagy a feladói konfigurációt.
A kutatást a content.notes mezőben tartsa; kimenő szövegként csak a content.subject és content.body használható. A piszkozat létrehozása biztosítja, hogy a kapcsolattartó a projekt résztvevője legyen. A frissítésekhez a legutóbbi olvasáskor visszaadott verziót kell használni; az ellenőrzött vagy elküldött piszkozatok módosítása elutasításra kerül. Az azonos újrapróbálkozások az eredeti piszkozatot adják vissza, új ellenőrzés létrehozása nélkül. Olvassa vissza a reviewUrl, draftVersion és contentHash értéket, a jóváhagyási/küldési állapotot, valamint a későbbi mailScoutelloId értéket.
Csak a hozzárendelt személy hagyhatja jóvá és küldheti el az üzenetet a meglévő ellenőrzési felületen. Az integrációk nem hagyhatnak jóvá, nem indíthatják el és nem küldhetik el az üzeneteket, még piszkozatírási hozzáféréssel sem. Régi piszkozatok átalakításakor őrizze meg az eredeti protokollokat, és hivatkozzon az új változatokra. A sorba állítási vagy bizonytalan kézbesítési hibákat ki kell vizsgálni; vakon újraküldeni tilos.
Közösségimédia-bejegyzések előkészítése
Adja meg szükség szerint a(z) social-channels.read, social-posts.read, social-post-drafts.read és social-post-drafts.write engedélyeket. A(z) members_list (members.read) segítségével lekérhetők a felülvizsgálók felhasználói azonosítói. A közösségi eszközök csak akkor jelennek meg, ha a hozzájuk tartozó hatókör engedélyezve van:
| Hatókör | Eszközök |
|---|---|
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 |
Olvassa be a csatornák képességeit és a Scoutello által létrehozott előzményeket, töltsön fel eszközöket, majd küldje be az összes csatornaváltozatot megnevezett felülvizsgálóval. A feltöltési eszközök HTTP PUT-utasításokat adnak vissza: az eredeti fájl bájtjait az MCP-n kívül kell továbbítani, majd a feltöltést a(z) { "assetId": "..." } használatával kell véglegesíteni. Ne ágyazzon base64-kódolású fájlokat az eszközargumentumokba.
Új vázlatokhoz használja a(z) expectedVersion: 0 elemet, függőben lévő módosításokhoz pedig az aktuális verziót. A(z) mode: "validate" nem hajt végre írási műveleteket. Az eszköz visszaadja a felülvizsgálati URL-t; a közzétételt vagy az ütemezést csak a vezérlőpultot használó személy hagyhatja jóvá. Nincs MCP-eszköz egy bejegyzés jóváhagyására, közzétételére, visszavonására vagy törlésére. A jóváhagyáshoz, az elutasítás okaihoz és a csatornánkénti kézbesítési eredményekhez kérdezze le a vázlat- és előzményeszközöket. A felülvizsgált vázlatokhoz a további javaslatokhoz új külső azonosító szükséges.
A bemeneti példákat, a feltöltési korlátokat, a lapozást és a késedelmes felülvizsgálatok kezelését lásd a közösségi bejegyzések emberi felülvizsgálathoz című részben.