Siirry pääsisältöön

MCP-integraatio

Modulaarisissa organisaatioissa yhdistetyllä organisaatiolla on oltava aktiivinen CRM-moduuli sekä integraation edellyttämät käyttöoikeusalueet. Taustalla oleva API palauttaa HTTP 403 -vastauksen kera module_not_active, kun CRM-käyttöoikeus ei ole käytettävissä. Ota moduulin käyttöoikeus käyttöön kohdassa Subscription ennen uutta yritystä; pelkkä API-avaimen vaihtaminen ei korjaa tätä virhettä.

Scoutello tarjoaa etäyhteyden kautta käytettävän Model Context Protocol (MCP) -palvelimen organisaation tietojen hallittuun käyttöön. Se käyttää samoja integraatioita, API-avaimia, käyttöoikeusalueita, tenant-tarkistuksia, nopeusrajoituksia ja tietueiden käsittelysääntöjä kuin Scoutello REST API.

Käytä MCP:tä, kun tekoälyasiakkaan tai -agentin tulee löytää Scoutellon toiminnot ja kutsua niitä työkaluina. Käytä RESTiä, kun sovellus tarvitsee perinteisiä HTTP-päätepisteitä tai generoidun OpenAPI-asiakkaan. Molemmat rajapinnat käyttävät samaa taustalla olevaa tietosopimusta.

Ennen yhdistämistä​

Organisaation ylläpitäjän on luotava integraatio kohdassa Organization settings → Developer/API. Avainta luotaessa tai vaihdettaessa:

  1. Valitse vain MCP-asiakkaan tarvitsemat luku- ja kirjoitusoikeudet.
  2. Tallenna koko sctl_api_-avain, kun se näytetään. Scoutello näyttää sen vain kerran.
  3. Tallenna avain MCP-asiakkaan salaisuus- tai ympäristömäärityksiin, ei lähdekoodin hallintaan.

Samaa integraatioavainta voi käyttää REST- ja MCP-kutsuissa. Erillisen, vain MCP:lle tarkoitetun avaimen luominen ei ole tarpeen eikä suositeltavaa. Aiemmat sctl_mcp_-avaimet eivät kelpaa.

Yhteysarvot​

Määritä asiakkaalle seuraavat arvot:

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

Korvaa YOUR_API_KEY tallennetulla integraatioavaimella. Asiakkaiden määritysmuodot vaihtelevat, mutta yllä olevat siirtotapa, URL-osoite ja HTTP-otsake pysyvät samoina. Jos asiakas ei voi määrittää Authorization-otsaketta, avaimen voi lähettää sen sijaan x-api-key-otsakkeessa. Älä määritä molempia otsakkeita.

Vanha https://admin.scoutello.com/api/mcp-URL-osoite säilyy yhteensopivuusaliaksena. Uusissa yhteyksissä tulee käyttää versioitua /api/v1/mcp-päätepistettä.

Yhteyden tarkistaminen​

Kun asiakas on muodostanut yhteyden, kutsu ensin whoami-työkalua. Se palauttaa nykyisen integraation ja organisaation, tunnistetietojen vanhenemis- ja käyttötiedot, nopeusrajoitusten tilan sekä myönnetyt käyttöoikeusalueet paljastamatta organisaation tietueita.

Jos whoami tunnistaa odottamattoman organisaation tai integraation, katkaise asiakkaan yhteys ja korjaa sen avain ennen muiden työkalujen kutsumista.

Työkalut ja käyttöoikeusalueet​

MCP-palvelin ilmoittaa vain nykyiselle avaimelle myönnetyt työkalut. Asiakas ei voi löytää tai kutsua kirjoitustyökalua pelkällä vastaavalla lukuoikeudella.

API-käyttöoikeusMCP-työkalut
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 (mukaan lukien osallistujien upsert-toiminnot)
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 (vain ihmisen tarkisteltavaksi valmistelua varten)
tags.readtags_list

whoami on aina käytettävissä todennetussa yhteydessä. Työkalujen syötteet ja tulokset noudattavat samoja skeemoja ja vastauskuoria kuin niihin liittyvät REST-toiminnot.

contacts_list hyväksyy rajatut search-arvot etu- ja sukunimien sekä yritysnimien yhteydessä, type, status ja tagIds (1–50 tunnisteen taulukko, joka vastaa mitä tahansa valittua tunnistetta). Kaikkien hakutunnisteiden on vastattava nimikenttää; kaikki suodattimet yhdistetään AND-operaatiolla. Säilytä nämä suodattimet jokaisella kohdistinsivulla. Esimerkiksi { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } löytää vastaavat olemassa olevat tilit ilman koko luettelon läpikäyntiä.

Scoutellon kirjautumiseen linkitetyt CRM:n ulkopuoliset kontaktit ovat luettavissa ja viitattavissa, mutta jäsenyys- ja tilikentät pysyvät piilotettuina ja kontaktien muokkaus suojattuna. Pelkkään ulkoiseen linkitykseen perustuvalla upsert-toiminnolla voi rekisteröidä luettavan kontaktin käyttämällä arvoja externalId, sen scoutelloId ja valinnaisen externalUpdatedAt; jätä kaikki CRM-kentät pois. Myöhemmissä yrityksissä ja metatietojen päivityksissä jätä scoutelloId pois. Lisätietoja on kontaktien rajoista ja linkityssäännöistä.

Kirjoita turvallisesti​

Eräpäivitystyökalut voivat muuttaa Scoutello-tietoja välittömästi. Ne ovat idempotentteja saman integraation ja ulkoisten tunnisteiden yhteydessä, mutta kutsujien tulee silti tarkistaa aiottu resurssi, organisaatio ja laajuus ennen muutosten käyttöönottoa.

Aseta mode arvoksi validate suorittaaksesi täsmäytyksen ja validoinnin ilman kirjoituksia. Tarkista tulokset ja toista kutsu sen jälkeen arvolla mode: "apply" hyväksyäksesi kelvolliset tietueet. MCP ei tarjoa poistotoimintoja.

Integraation keskeyttäminen hylkää sekä REST- että MCP-pyynnöt, joissa käytetään sen avaimia. Avaimen kierrättäminen korvaa tunnistetiedon, ja kumoaminen poistaa pysyvästi käytöstä kaikki integraatioon kuuluvat tunnistetiedot.

Vianmääritys​

TulosTarkistettava asia
401-todennusvirheVarmista, että koko avain on mukana ja otsakkeessa käytetään Bearer-arvoa ilman avainta ympäröiviä lainausmerkkejä.
403-valtuutusvirheMyönnä tarvittava laajuus kierrättämällä integraatioavain ja päivitä asiakasohjelma korvaavalla avaimella.
404 MCP-URL-osoitteessaVarmista, että URL-osoitteen lopussa on /api/v1/mcp. MCP-palvelua ei ehkä ole vielä otettu käyttöön tässä Scoutello-ympäristössä.
429 nopeusrajoitusvirheOdota palautettuun nollautumisaikaan asti ennen uutta yritystä. REST ja MCP käyttävät samaa integraation kiintiötä.
Työkalu puuttuuTarkista avaimen laajuudet komennolla whoami. Käytöstä puuttuvat työkalut jätetään tarkoituksella pois etsinnästä.

Tietuekentät, sivutus, erätoiminta ja virhevastausrakenteet on kuvattu Scoutello API -viitteessä.

Yhdistetty projektisuunnittelu​

Luo ensin projekti, sitten sen virstanpylväät ja lopuksi tehtävät sekä protokollat käyttämällä pysyviä integraation ulkoisia tunnisteita. Uusien virstanpylväiden käyttöoikeudet edellyttävät milestones.read/milestones.write-arvoa. Myönnä members.read, jotta määritettävissä olevat jäsenet voidaan hakea. Olemassa olevia tunnistetietoja ei laajenneta automaattisesti. Kun käyttöoikeudet on kierrätetty tai myönnetty, päivitä työkalujen etsintä ja tarkista whoami.

Käytä projektin tai virstanpylvään assignedContacts-kentässä jäsenen Customer ID -tunnistetta ja tehtävän assignedScoutelloUserIds- tai mahdollisuuden ownerScoutelloUserId-kentässä User ID -tunnistetta. Tehtävä- ja protokollaviittaukset hyväksyvät projectScoutelloId- tai projectExternalId-arvon sekä vastaavat virstanpylväs- ja mahdollisuuspareja. Pelkkään virstanpylvääseen perustuvissa linkeissä projekti päätellään automaattisesti. Ristiriidat hylkäävät eräkohteen. Projektin osallistujat lisätään täydentävinä päivityksinä, ja pois jätetyt merkinnät säilytetään.

Protokollat tukevat yhteystiedottomia projekti- ja virstanpylväsmuistiinpanoja sekä draft/final-tilaa. Tämän yhdistetyn työn tuonnit ovat hiljaisia eivätkä koskaan lähetä viestintää. Luettelotyökalut tarjoavat samat entiteettikohtaiset projekti-, tila-, määritys- ja eräpäiväsuodattimet kuin REST. Välitä täsmälleen samat suodattimet, mukaan lukien updatedSince, jokaiselle kohdistinsivulle. Katso täydellinen sopimus ja null-/pois jätettyjen arvojen semantiikka API-viitteestä.

Validoi jokainen riippuva erä, ota se käyttöön, tarkista jokainen tulos ja lue tietueet uudelleen ennen kuin pidät tietojen täyttämistä valmiina. Kuiva-ajo ei voi ratkaista yläkohteita, jotka ovat olemassa vain toisessa kuiva-ajossa. Kun epäselvää alkuperäistä linkkiä yritetään uudelleen käyttämällä scoutelloId-arvoa, lue ensin ulkoisen tunnisteen perusteella. Bootstrap-tunnisteita ei voi toistaa sen jälkeen, kun linkki on olemassa.

Myyntiprojektiagentin ohjeet​

Jokaisen myyntiprojektia varten luodun tai uudelleenkäytetyn yhteystiedon tulee viitata kyseiseen projektiin eksplisiittisesti projectScoutelloId- tai projectExternalId-arvolla kentässä contacts_batch_upsert. Projektin mainitseminen muistiinpanoissa tai ulkoisessa tunnisteessa ei muodosta jäsenyyttä. Projektiviittauksia sisältävät yhteystietojen kirjoitukset edellyttävät myös projects.write-arvoa. Lue yhteystieto uudelleen käyttämällä contacts.read- ja projects.read-arvoja ja varmista projectParticipations. Säilytä olemassa olevat jäsenyydet ja ryhmät. Projektin ulkopuoliset yleiset yhteystiedot eivät edellytä projektiviittausta.

Pidä yritykset ja varmennetut henkilöt erillisinä yhteystietoina. Linkitä henkilö yritykseen companyScoutelloId- tai companyExternalId-arvolla, älä pelkästään companyName-arvolla. Yhteystieto-, yrityssuhde- ja jäsenyysmuutokset ovat atomisia kunkin eräkohteen osalta. Virheelliset viittaukset eivät jätä yhteystietoa osittain luoduksi. Älä keksi henkilöitä tai lisää alkuperää ilmaisevia tunnisteita.

Valmistele lähtevät sähköpostit käyttämällä mail_drafts_batch_upsert-arvoa, älä koskaan protokollan tekstiosina. Myönnä uudet mail-drafts.read- ja mail-drafts.write-laajuudet erikseen. Valmistelu edellyttää myös contacts.read- ja projects.write-laajuuksia. Olemassa oleville tunnistetiedoille ei myönnetä uusia oikeuksia automaattisesti. Käytä pysyvää ulkoista tunnistetta, expectedVersion: 0-arvoa luomiseen, eksplisiittisiä projekti- ja yhteystietoviittauksia, hyväksytyn hyväksyjän User ID -tunnistetta sekä määritettyä organization- tai personal-lähettäjän laajuutta. Älä koskaan arvaa vastaanottajan osoitetta tai lähettäjäasetusta.

Pidä tutkimus content.notes-arvossa. Vain content.subject ja content.body sisältävät lähtevää tekstiä. Luonnoksen luominen varmistaa, että yhteystieto on projektin osallistuja. Päivityksissä on käytettävä viimeisimmän luvun palauttamaa versiota. Tarkistetut tai lähetetyt luonnokset hylkäävät muokkaukset. Identtiset uudelleenyritykset palauttavat alkuperäisen luonnoksen luomatta uutta tarkistettavaa luonnosta. Lue uudelleen sen reviewUrl-, draftVersion- ja contentHash-arvot, hyväksymis-/lähetysstatus sekä lopullinen mailScoutelloId.

Vain määritetty henkilö voi hyväksyä ja lähettää viestin olemassa olevan tarkistusnäkymän kautta. Integraatiot eivät voi hyväksyä, välittää tai lähettää viestejä edes luonnosten kirjoitusoikeudella. Säilytä alkuperäiset protokollat, kun vanhoja luonnoksia muunnetaan, ja viittaa korvaaviin luonnoksiin. Jonossa olevat tai epäselvät toimitusvirheet on tutkittava. Älä lähetä viestiä sokkona uudelleen.

Sosiaalisen median julkaisujen valmistelu​

Myönnä social-channels.read, social-posts.read, social-post-drafts.read ja social-post-drafts.write tarvittaessa. members_list (members.read) voi selvittää arvioijien käyttäjätunnuksia. Sosiaalisen median työkalut ilmoitetaan vain, kun niiden käyttöoikeus on myönnetty:

KäyttöoikeusTyökalut
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

Lue kanavien käyttöoikeudet ja Scoutello-sovelluksen luoma historia, lataa aineistot ja lähetä sitten täydelliset kanavaversiot nimetyn arvioijan tarkistettaviksi. Lataustyökalut palauttavat HTTP PUT -ohjeet: siirrä alkuperäisen tiedoston tavut MCP:n ulkopuolella ja viimeistele lataus sitten { "assetId": "..." }-komennolla. Älä upota base64-tiedostoja työkalukutsujen argumentteihin.

Käytä expectedVersion: 0-komentoa uusille luonnoksille ja nykyistä versiota odottaville muutoksille. mode: "validate" ei tee muutoksia. Työkalu palauttaa tarkistusosoitteen; vain hallintapaneelia käyttävä henkilö voi hyväksyä julkaisemisen tai ajastamisen. MCP-työkalulla ei voi hyväksyä, julkaista, peruuttaa tai poistaa julkaisua. Seuraa luonnos- ja historiatyökaluilla hyväksyntää, hylkäyksen syitä ja kanavakohtaisia toimitustuloksia. Tarkistetut luonnokset edellyttävät uutta ulkoista tunnusta uusia ehdotuksia varten.

Katso sosiaalisen median julkaisut ihmisen tarkistettaviksi, jossa on esimerkkejä syötteistä, latausrajat, sivutus ja myöhästyneitä tarkistuksia koskevat tiedot.