Treci la conținutul principal

Integrarea MCP

Pentru organizațiile modulare, organizația conectată trebuie să aibă un modul CRM activ, precum și domeniile de acces necesare integrării. API-ul de bază returnează HTTP 403 cu module_not_active atunci când accesul la CRM nu este disponibil. Rezolvați accesul la modul în Abonament înainte de a reîncerca; schimbarea cheii API nu remediază singură această eroare.

Scoutello pune la dispoziție un server Model Context Protocol (MCP) la distanță, pentru acces controlat la datele organizației. Acesta utilizează aceleași integrări, chei API, domenii de acces, verificări ale entității locatare, limite de rată și comportament privind înregistrările ca API-ul REST Scoutello.

Utilizați MCP atunci când un client sau agent AI trebuie să descopere și să apeleze operațiunile Scoutello ca instrumente. Utilizați REST atunci când o aplicație are nevoie de endpointuri HTTP convenționale sau de un client OpenAPI generat. Ambele interfețe folosesc același contract de date de bază.

Înainte de conectare​

Un administrator al organizației trebuie să creeze o integrare în Setările organizației → Developer/API. La crearea sau rotirea cheii:

  1. Selectați doar domeniile de acces pentru citire și scriere de care are nevoie clientul MCP.
  2. Salvați cheia sctl_api_ completă atunci când este afișată. Scoutello o afișează o singură dată.
  3. Stocați cheia în configurația secretă sau de mediu a clientului MCP, nu în sistemul de control al versiunilor.

Aceeași cheie de integrare poate apela REST și MCP. Crearea unei chei separate, specifice MCP, nu este necesară și nici recomandată. Cheile sctl_mcp_ vechi nu sunt acceptate.

Valori de conectare​

Configurați clientul cu aceste valori:

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

Înlocuiți YOUR_API_KEY cu cheia de integrare salvată. Formatele de configurare diferă între clienți, însă transportul, adresa URL și antetul HTTP de mai sus rămân aceleași. Dacă un client nu poate seta Authorization, poate trimite cheia în x-api-key. Nu configurați ambele antete.

Adresa URL https://admin.scoutello.com/api/mcp moștenită rămâne un alias de compatibilitate. Conexiunile noi trebuie să utilizeze endpointul /api/v1/mcp cu versiune.

Verificarea conexiunii​

După conectarea clientului, apelați mai întâi instrumentul whoami. Acesta returnează integrarea și organizația curente, informații despre expirarea și utilizarea acreditării, starea limitelor de rată și domeniile de acces acordate, fără a expune înregistrările organizației.

Dacă whoami identifică o organizație sau o integrare neașteptată, deconectați clientul și corectați cheia înainte de a apela un alt instrument.

Instrumente și domenii de acces​

Serverul MCP afișează doar instrumentele acordate de cheia curentă. Un client nu poate descoperi sau apela un instrument de scriere folosind doar domeniul de acces corespunzător pentru citire.

Domeniu de acces APIInstrumente 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 (inclusiv actualizări ale participanților)
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 (doar pentru pregătirea verificării umane)
tags.readtags_list

whoami este disponibil întotdeauna pentru o conexiune autentificată. Intrările și rezultatele instrumentelor urmează aceleași scheme și plicuri de răspuns ca operațiunile REST asociate.

contacts_list acceptă search limitat în câmpurile pentru prenume/nume și companie, type, status și tagIds (o matrice cu 1–50 de ID-uri, care corespunde oricărei etichete selectate). Toate tokenurile de căutare trebuie să corespundă unui câmp de nume; toate filtrele sunt combinate cu AND. Păstrați aceste filtre pentru fiecare pagină cu cursor. De exemplu, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } găsește conturile existente corespunzătoare fără a parcurge întregul inventar.

Contactele CRM care nu sunt membre, dar sunt asociate unei autentificări Scoutello, pot fi citite și utilizate ca referințe, în timp ce câmpurile privind apartenența și contul rămân ascunse, iar editările contactelor rămân protejate. O operațiune upsert bazată exclusiv pe o legătură externă poate înregistra un contact care poate fi citit folosind externalId, scoutelloId și, opțional, externalUpdatedAt; omiteți toate câmpurile CRM. La reîncercările sau actualizările ulterioare ale metadatelor, omiteți scoutelloId. Consultați limita contactelor și regulile de asociere.

Scriere în siguranță​

Instrumentele de upsert în lot pot modifica imediat datele din Scoutello. Sunt idempotente pentru aceeași integrare și aceleași ID-uri externe, însă este recomandat ca apelantul să verifice în continuare resursa, organizația și domeniul de aplicare vizate înainte de aplicarea modificărilor.

Setați mode la validate pentru a efectua potrivirea și validarea fără a scrie date. După inspectarea rezultatelor, repetați apelul cu mode: "apply" pentru a accepta înregistrările valide. MCP nu expune operațiuni de ștergere.

Suspendarea unei integrări respinge atât cererile REST, cât și pe cele MCP care folosesc cheile acesteia. Rotirea înlocuiește acreditarea, iar revocarea dezactivează permanent toate acreditările care aparțin integrării.

Depanare​

RezultatCe trebuie verificat
Eroare de autentificare 401Confirmați că este prezentă cheia completă și că antetul folosește Bearer, fără ghilimele în jurul cheii.
Eroare de autorizare 403Acordați domeniul de aplicare necesar rotind cheia integrării, apoi actualizați clientul cu cheia de înlocuire.
404 la adresa URL MCPConfirmați că adresa URL se termină în /api/v1/mcp. Este posibil ca serviciul MCP să nu fie încă activat în acel mediu Scoutello.
Eroare de limitare a ratei 429Așteptați până la momentul de resetare returnat înainte de a reîncerca. REST și MCP consumă aceeași cotă de integrare.
Instrument lipsăVerificați domeniile de aplicare ale cheii cu whoami; instrumentele indisponibile sunt omise intenționat din procesul de descoperire.

Pentru câmpurile înregistrărilor, paginare, comportamentul loturilor și structura erorilor, consultați în continuare referința API Scoutello.

Planificarea proiectelor conectate​

Creați un proiect, apoi obiectivele acestuia, urmate de sarcini și protocoale, folosind ID-uri externe stabile ale integrării. Pentru acces la obiectivele noi sunt necesare milestones.read/milestones.write; acordați members.read pentru a identifica membrii care pot fi alocați. Acreditările existente nu primesc automat domenii de acces suplimentare. După rotirea sau acordarea accesului, reîmprospătați descoperirea instrumentelor și inspectați whoami.

Folosiți ID-urile Customer ale membrilor pentru assignedContacts al proiectului/obiectivului și ID-urile User pentru assignedScoutelloUserIds al sarcinii sau ownerScoutelloUserId al oportunității. Referințele sarcinilor/protocoalelor acceptă projectScoutelloId sau projectExternalId, precum și perechile echivalente pentru obiectiv/oportunitate. Legăturile care includ doar obiectivul deduc proiectul; neconcordanțele resping elementul din lot. Participanții la proiect sunt actualizați prin upsert aditiv, iar intrările omise sunt păstrate.

Protocoalele acceptă note de proiect/obiectiv fără contact și starea draft/final. Importurile acestor activități conectate sunt silențioase și nu trimit niciodată comunicări. Instrumentele de listare expun aceleași filtre specifice entității pentru proiect, stare, alocare și termen-limită ca REST. Transmiteți filtrele exacte, inclusiv updatedSince, prin fiecare pagină de cursor. Consultați referința API pentru contractul complet și semantica valorilor nule/omise.

Validați fiecare lot dependent, aplicați-l, inspectați fiecare rezultat și citiți din nou înregistrările înainte de a considera popularea finalizată. O execuție de test nu poate rezolva părinți care există doar într-o altă execuție de test. Când reîncercați o legătură inițială ambiguă folosind scoutelloId, citiți mai întâi după ID-ul extern; ID-urile de inițializare nu pot fi redate după ce legătura există.

Instrucțiuni pentru agentul de proiecte de vânzări​

Fiecare contact creat sau reutilizat pentru un proiect de vânzări trebuie să facă referire explicită la proiect folosind projectScoutelloId sau projectExternalId în contacts_batch_upsert. Menționarea unui proiect în note sau într-un ID extern nu reprezintă apartenență. Scrierile contactelor cu referințe la proiecte necesită, de asemenea, projects.write. Citiți din nou contactul folosind contacts.read și projects.read și verificați projectParticipations; păstrați apartenențele și grupurile existente. Contactele generice din afara unui proiect nu necesită o referință la proiect.

Păstrați companiile și persoanele verificate ca contacte separate. Asociați o persoană companiei folosind companyScoutelloId sau companyExternalId, nu doar companyName. Modificările contactului, relației cu compania și apartenenței sunt atomice pentru fiecare element al lotului; referințele nevalide nu lasă în urmă un contact parțial. Nu inventați persoane și nu aplicați etichete de proveniență.

Pregătiți e-mailurile de trimis folosind mail_drafts_batch_upsert, niciodată ca texte de protocoale. Acordați explicit noile domenii mail-drafts.read și mail-drafts.write; pregătirea necesită, de asemenea, contacts.read și projects.write. Acreditările existente nu primesc automat permisiuni noi. Folosiți un ID extern stabil, expectedVersion: 0 pentru creare, referințe explicite la proiect/contact, ID-ul User al unei persoane care a aprobat și un domeniu de trimitere configurat organization sau personal. Nu ghiciți niciodată adresa destinatarului sau configurația expeditorului.

Păstrați cercetarea în content.notes; doar content.subject și content.body reprezintă text destinat trimiterii. Crearea unei schițe asigură că persoana de contact este participantă la proiect. Actualizările trebuie să folosească versiunea returnată de cea mai recentă citire; schițele verificate sau expediate resping modificările. Reîncercările identice returnează schița inițială fără a crea o altă verificare. Citiți din nou reviewUrl, draftVersion, contentHash, starea aprobării/expedierii și eventualul mailScoutelloId.

Doar persoana umană alocată poate aproba și trimite prin ecranul de verificare existent. Integrările nu pot aproba, expedia sau trimite, nici chiar cu acces de scriere pentru schițe. Păstrați protocoalele originale la convertirea schițelor vechi și faceți trimiteri încrucișate către înlocuitori. Erorile de livrare puse în coadă sau ambigue necesită investigare, niciodată retrimitere automată.

Pregătirea postărilor sociale​

Acordă social-channels.read, social-posts.read, social-post-drafts.read și social-post-drafts.write după caz. members_list (members.read) poate identifica ID-urile utilizatorilor recenzenți. Instrumentele sociale sunt afișate doar atunci când domeniul lor de acces este acordat:

Domeniu de accesInstrumente
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

Citește capabilitățile canalului și istoricul creat de Scoutello, încarcă materialele, apoi trimite variante complete pentru canale, împreună cu un recenzent nominalizat. Instrumentele de încărcare returnează instrucțiuni HTTP PUT: transferă octeții fișierului original în afara MCP, apoi finalizează încărcarea cu { "assetId": "..." }. Nu încorpora fișiere codificate în base64 în argumentele instrumentelor.

Folosește expectedVersion: 0 pentru ciorne noi și versiunea curentă pentru reviziile în așteptare. mode: "validate" nu efectuează operațiuni de scriere. Instrumentul returnează adresa URL pentru recenzie; doar o persoană care utilizează tabloul de bord poate aproba publicarea sau programarea. Nu există niciun instrument MCP pentru aprobarea, publicarea, anularea sau ștergerea unei postări. Interoghează periodic instrumentele pentru ciorne/istoric pentru a verifica aprobarea, motivele respingerii și rezultatele livrării pentru fiecare canal. Ciornele recenzate necesită un ID extern nou pentru propuneri ulterioare.

Consultă postările sociale pentru recenzie umană pentru exemple de intrări, limite de încărcare, paginare și comportamentul recenziilor întârziate.