Vai al contenuto principale

Integrazione MCP

Per le organizzazioni modulari, l'organizzazione collegata deve avere un modulo CRM attivo e gli ambiti richiesti dall'integrazione. L'API sottostante restituisce HTTP 403 con module_not_active quando l'accesso al CRM non è disponibile. Risolvi l'accesso al modulo in Abbonamento prima di riprovare; cambiare solo la chiave API non risolve questo errore.

Scoutello fornisce un server Model Context Protocol (MCP) remoto per consentire un accesso controllato ai dati dell'organizzazione. Utilizza le stesse integrazioni, chiavi API, ambiti, verifiche del tenant, limiti di frequenza e comportamento sui record dell'API REST di Scoutello.

Usa MCP quando un client o un agente AI deve individuare e chiamare le operazioni di Scoutello come strumenti. Usa REST quando un'applicazione necessita di endpoint HTTP convenzionali o di un client OpenAPI generato. Entrambe le interfacce utilizzano lo stesso contratto dati sottostante.

Prima della connessione​

Un amministratore dell'organizzazione deve creare un'integrazione in Impostazioni dell'organizzazione → Sviluppatore/API. Durante la creazione o la rotazione della chiave:

  1. Seleziona solo gli ambiti di lettura e scrittura necessari al client MCP.
  2. Salva la chiave sctl_api_ completa quando viene mostrata. Scoutello la visualizza una sola volta.
  3. Archivia la chiave nel segreto o nella configurazione dell'ambiente del client MCP, non nel controllo del codice sorgente.

La stessa chiave di integrazione può chiamare REST e MCP. Creare una seconda chiave specifica per MCP non è necessario né consigliato. Le chiavi sctl_mcp_ precedenti non sono accettate.

Valori di connessione​

Configura il client con questi valori:

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

Sostituisci YOUR_API_KEY con la chiave di integrazione salvata. I formati di configurazione dei client variano, ma il trasporto, l'URL e l'intestazione HTTP riportati sopra rimangono invariati. Se un client non può impostare Authorization, può inviare la chiave in x-api-key. Non configurare entrambe le intestazioni.

L'URL https://admin.scoutello.com/api/mcp precedente rimane un alias di compatibilità. Le nuove connessioni devono utilizzare l'endpoint /api/v1/mcp con versione.

Verifica della connessione​

Dopo la connessione del client, chiama prima lo strumento whoami. Restituisce l'integrazione e l'organizzazione attuali, la scadenza delle credenziali e le informazioni sull'utilizzo, lo stato del limite di frequenza e gli ambiti concessi, senza esporre i record dell'organizzazione.

Se whoami identifica un'organizzazione o un'integrazione imprevista, disconnetti il client e correggi la chiave prima di chiamare un altro strumento.

Strumenti e ambiti​

Il server MCP pubblicizza solo gli strumenti concessi dalla chiave corrente. Un client non può individuare o chiamare uno strumento di scrittura disponendo solo dell'ambito di lettura corrispondente.

Ambito APIStrumenti 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 (inclusi gli upsert dei partecipanti)
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 (solo per la preparazione della revisione umana)
tags.readtags_list

whoami è sempre disponibile per una connessione autenticata. Gli input e i risultati degli strumenti seguono gli stessi schemi e gli stessi envelope di risposta delle operazioni REST collegate.

contacts_list accetta search con limiti definiti tra nomi, cognomi e nomi delle aziende, type, status e tagIds (un array di 1–50 ID, corrispondenti a qualsiasi tag selezionato). Tutti i token di ricerca devono corrispondere a un campo nome; tutti i filtri vengono combinati con AND. Mantieni questi filtri in ogni pagina del cursore. Ad esempio, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } trova gli account esistenti corrispondenti senza analizzare l'intero inventario.

I contatti CRM non membri collegati a un accesso Scoutello sono leggibili e utilizzabili come riferimenti, mentre i campi relativi a iscrizione e account rimangono nascosti e le modifiche ai contatti restano protette. Un upsert basato esclusivamente sul collegamento esterno può registrare un contatto leggibile usando externalId, il relativo scoutelloId e l'externalUpdatedAt facoltativo; ometti tutti i campi CRM. I tentativi successivi e gli aggiornamenti dei metadati omettono scoutelloId. Consulta le regole sui confini e sui collegamenti dei contatti.

Scrittura sicura​

Gli strumenti di upsert in batch possono modificare immediatamente i dati di Scoutello. Sono idempotenti per la stessa integrazione e gli stessi ID esterni, ma chi effettua la chiamata dovrebbe comunque verificare la risorsa, l’organizzazione e l’ambito previsti prima di applicare le modifiche.

Impostare mode su validate esegue il matching e la convalida senza scrivere dati. Dopo aver esaminato i risultati, ripetere la chiamata con mode: "apply" per accettare i record validi. MCP non espone operazioni di eliminazione.

La sospensione di un’integrazione rifiuta le richieste REST e MCP che utilizzano le relative chiavi. La rotazione sostituisce la relativa credenziale, mentre la revoca disabilita definitivamente ogni credenziale appartenente all’integrazione.

Risoluzione dei problemi​

RisultatoCosa verificare
401 errore di autenticazioneVerificare che sia presente la chiave completa e che l’header utilizzi Bearer, senza virgolette intorno alla chiave.
403 errore di autorizzazioneConcedere l’ambito richiesto ruotando la chiave dell’integrazione, quindi aggiornare il client con la chiave sostitutiva.
404 all’URL MCPVerificare che l’URL termini con /api/v1/mcp. Il servizio MCP potrebbe non essere ancora abilitato in quell’ambiente Scoutello.
429 errore di limite di frequenzaAttendere l’orario di reimpostazione restituito prima di riprovare. REST e MCP consumano la stessa quota dell’integrazione.
Strumento mancanteVerificare gli ambiti della chiave con whoami; gli strumenti non disponibili vengono omessi intenzionalmente dal rilevamento.

Per i campi dei record, la paginazione, il comportamento dei batch e gli envelope degli errori, consultare la documentazione di riferimento dell’API Scoutello.

Pianificazione di progetti connessi​

Creare un progetto, quindi le relative milestone e infine attività e protocolli utilizzando ID esterni stabili dell’integrazione. Per accedere alle nuove milestone sono necessari milestones.read/milestones.write; concedere members.read per cercare i membri assegnabili. Le credenziali esistenti non ricevono automaticamente ambiti più ampi. Dopo aver ruotato o concesso l’accesso, aggiornare il rilevamento degli strumenti ed esaminare whoami.

Utilizzare gli ID cliente dei membri per assignedContacts del progetto o della milestone e gli ID utente per assignedScoutelloUserIds dell’attività o ownerScoutelloUserId dell’opportunità. I riferimenti di attività e protocollo accettano projectScoutelloId o projectExternalId, oltre alle corrispondenti coppie milestone/opportunità. I collegamenti che indicano solo la milestone ricavano il progetto; le incoerenze rifiutano l’elemento del batch. I partecipanti al progetto vengono gestiti tramite upsert cumulativi e le voci omesse vengono mantenute.

I protocolli supportano note di progetto o milestone senza contatto e lo stato draft/final. Le importazioni di questo lavoro connesso sono silenziose e non inviano mai comunicazioni. Gli strumenti di elenco espongono gli stessi filtri REST specifici per entità relativi a progetto, stato, assegnazione e scadenza. Mantenere gli stessi filtri esatti, incluso updatedSince, in ogni pagina del cursore. Consultare il riferimento dell’API per il contratto completo e la semantica dei valori null/omessi.

Convalidare ogni batch dipendente, applicarlo, esaminare ogni risultato e rileggere i record prima di considerare completata la compilazione. Un’esecuzione simulata non può risolvere genitori che esistono solo in un’altra esecuzione simulata. Quando si riprova un collegamento iniziale ambiguo utilizzando scoutelloId, leggere prima tramite ID esterno; gli ID di bootstrap non possono essere riutilizzati una volta creato il collegamento.

Istruzioni per l’agente dei progetti commerciali​

Ogni contatto creato o riutilizzato per un progetto commerciale deve fare esplicito riferimento a quel progetto utilizzando projectScoutelloId o projectExternalId in contacts_batch_upsert. Menzionare un progetto nelle note o in un ID esterno non costituisce un’appartenenza. Le scritture dei contatti con riferimenti al progetto richiedono inoltre projects.write. Rileggere il contatto con contacts.read e projects.read e verificare projectParticipations; preservare le appartenenze e i gruppi esistenti. I contatti generici esterni a un progetto non richiedono un riferimento al progetto.

Mantenere aziende e persone verificate come contatti separati. Collegare una persona all’azienda con companyScoutelloId o companyExternalId, non solo con companyName. Le modifiche ai contatti, alle relazioni aziendali e alle appartenenze sono atomiche per ogni elemento del batch; i riferimenti non validi non lasciano contatti parziali. Non inventare persone né applicare tag di provenienza.

Preparare le email in uscita con mail_drafts_batch_upsert, mai come corpi di protocollo. Concedere esplicitamente i nuovi ambiti mail-drafts.read e mail-drafts.write; la preparazione richiede inoltre contacts.read e projects.write. Le credenziali esistenti non ricevono automaticamente nuove autorizzazioni. Utilizzare un ID esterno stabile, expectedVersion: 0 per la creazione, riferimenti espliciti a progetto e contatto, l’ID utente di una persona approvatrice accettata e un ambito mittente organization o personal configurato. Non indovinare mai l’indirizzo del destinatario o la configurazione del mittente.

Mantenere la ricerca in content.notes; solo content.subject e content.body costituiscono contenuto in uscita. La creazione della bozza garantisce che il contatto sia un partecipante al progetto. Gli aggiornamenti devono utilizzare la versione restituita dalla lettura più recente; le bozze esaminate o inviate rifiutano le modifiche. I tentativi identici restituiscono la bozza originale senza creare un’altra revisione. Rileggere reviewUrl, draftVersion, contentHash, lo stato di approvazione/invio e l’eventuale mailScoutelloId.

Solo la persona assegnata può approvare e inviare tramite la schermata di revisione esistente. Le integrazioni non possono approvare, inoltrare o inviare, nemmeno con accesso alla scrittura delle bozze. Preservare i protocolli originali quando si convertono vecchie bozze e inserire riferimenti incrociati alle sostituzioni. Gli errori di consegna in coda o ambigui richiedono un’indagine, mai un nuovo invio alla cieca.

Preparazione dei post social​

Concedi social-channels.read, social-posts.read, social-post-drafts.read e social-post-drafts.write secondo necessità. members_list (members.read) può individuare gli ID utente delle persone incaricate della revisione. Gli strumenti social vengono pubblicizzati solo quando il relativo ambito è concesso:

AmbitoStrumenti
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

Leggi le funzionalità dei canali e la cronologia creata da Scoutello, carica gli asset, quindi invia varianti complete dei canali con una persona incaricata della revisione. Gli strumenti di caricamento restituiscono istruzioni HTTP PUT: trasferisci i byte del file originale al di fuori di MCP, quindi completa il caricamento con { "assetId": "..." }. Non incorporare file base64 negli argomenti degli strumenti.

Usa expectedVersion: 0 per le nuove bozze e la versione corrente per le revisioni in sospeso. mode: "validate" non esegue scritture. Lo strumento restituisce l'URL della revisione; solo una persona che utilizza il dashboard può approvare la pubblicazione o la programmazione. Non esiste alcuno strumento MCP per approvare, pubblicare, annullare o eliminare un post. Interroga gli strumenti per bozze e cronologia per verificare l'approvazione, i motivi del rifiuto e i risultati della distribuzione per ogni canale. Le bozze revisionate richiedono un nuovo ID esterno per ulteriori proposte.

Consulta post social per la revisione umana per esempi di input, limiti di caricamento, paginazione e comportamento in caso di revisione tardiva.