Aller au contenu principal

Intégration MCP

Pour les organisations modulaires, l’organisation connectée doit disposer d’un module CRM actif ainsi que des portées requises par l’intégration. L’API sous-jacente renvoie HTTP 403 avec module_not_active lorsque l’accès au CRM est indisponible. Accordez l’accès au module dans Subscription avant de réessayer ; changer uniquement la clé API ne corrige pas cette erreur.

Scoutello fournit un serveur Model Context Protocol (MCP) distant pour permettre un accès contrôlé aux données de l’organisation. Il utilise les mêmes intégrations, clés API, portées, contrôles du locataire, limites de débit et comportements liés aux enregistrements que l’API REST de Scoutello.

Utilisez MCP lorsqu’un client ou un agent IA doit découvrir et appeler les opérations de Scoutello sous forme d’outils. Utilisez REST lorsqu’une application a besoin de points de terminaison HTTP classiques ou d’un client OpenAPI généré. Les deux interfaces utilisent le même contrat de données sous-jacent.

Avant la connexion​

Une personne administratrice de l’organisation doit créer une intégration dans Organization settings → Developer/API. Lors de la création ou de la rotation de sa clé :

  1. Sélectionnez uniquement les portées de lecture et d’écriture dont le client MCP a besoin.
  2. Enregistrez la clé sctl_api_ complète lorsqu’elle s’affiche. Scoutello ne l’affiche qu’une seule fois.
  3. Stockez la clé dans le secret ou la configuration d’environnement du client MCP, et non dans le code source.

La même clé d’intégration peut appeler REST et MCP. La création d’une seconde clé dédiée à MCP n’est ni nécessaire ni recommandée. Les anciennes clés sctl_mcp_ ne sont pas acceptées.

Valeurs de connexion​

Configurez le client avec les valeurs suivantes :

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

Remplacez YOUR_API_KEY par la clé d’intégration enregistrée. Les formats de configuration varient selon les clients, mais le transport, l’URL et l’en-tête HTTP ci-dessus restent identiques. Si un client ne peut pas définir Authorization, il peut envoyer la clé dans x-api-key à la place. Ne configurez pas les deux en-têtes.

L’URL https://admin.scoutello.com/api/mcp héritée reste un alias de compatibilité. Les nouvelles connexions doivent utiliser le point de terminaison versionné /api/v1/mcp.

Vérifier la connexion​

Une fois le client connecté, appelez d’abord l’outil whoami. Il renvoie l’intégration et l’organisation actuelles, les informations d’expiration et d’utilisation des identifiants, l’état des limites de débit ainsi que les portées accordées, sans exposer les enregistrements de l’organisation.

Si whoami identifie une organisation ou une intégration inattendue, déconnectez le client et corrigez sa clé avant d’appeler un autre outil.

Outils et portées​

Le serveur MCP n’annonce que les outils accordés par la clé actuelle. Un client ne peut pas découvrir ni appeler un outil d’écriture avec la seule portée de lecture correspondante.

Portée APIOutils 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 (y compris les mises à jour des participants)
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 (préparation pour examen humain uniquement)
tags.readtags_list

whoami est toujours disponible pour une connexion authentifiée. Les entrées et les résultats des outils suivent les mêmes schémas et enveloppes de réponse que les opérations REST associées.

contacts_list accepte des search limitées sur les noms, prénoms et noms d’entreprise, type, status et tagIds (un tableau de 1 à 50 identifiants correspondant à une étiquette sélectionnée). Tous les jetons de recherche doivent correspondre à un champ de nom ; tous les filtres sont combinés avec AND. Conservez ces filtres sur chaque page parcourue avec un curseur. Par exemple, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } recherche les comptes existants correspondants sans analyser l’intégralité de l’inventaire.

Les contacts CRM non membres associés à un compte Scoutello sont lisibles et peuvent être référencés, tandis que les champs d’adhésion et de compte restent masqués et que les modifications de contact restent protégées. Une mise à jour limitée au lien externe peut enregistrer un contact lisible à l’aide de externalId, de son scoutelloId et, facultativement, de externalUpdatedAt ; omettez tous les champs CRM. Lors des nouvelles tentatives ou des mises à jour de métadonnées, omettez scoutelloId. Consultez les règles de séparation et de liaison des contacts.

Effectuer les écritures en toute sécurité​

Les outils de mise à jour par lot peuvent modifier immédiatement les données de Scoutello. Ils sont idempotents pour une même intégration et de mêmes identifiants externes, mais les personnes appelantes doivent tout de même vérifier la ressource, l’organisation et le périmètre concernés avant d’appliquer les modifications.

Définissez mode sur validate pour effectuer la mise en correspondance et la validation sans rien enregistrer. Après avoir inspecté les résultats, répétez l’appel avec mode: "apply" pour accepter les enregistrements valides. MCP n’expose aucune opération de suppression.

La mise en pause d’une intégration rejette les requêtes REST et MCP utilisant ses clés. La rotation remplace ses identifiants, tandis que la révocation désactive définitivement tous les identifiants associés à l’intégration.

Résolution des problèmes​

RésultatVérification à effectuer
401 erreur d’authentificationVérifiez que la clé complète est présente et que l’en-tête utilise Bearer, sans guillemets autour de la clé.
403 erreur d’autorisationAccordez le périmètre requis en effectuant une rotation de la clé d’intégration, puis mettez à jour le client avec la clé de remplacement.
404 à l’URL MCPVérifiez que l’URL se termine par /api/v1/mcp. Le service MCP n’est peut-être pas encore activé dans cet environnement Scoutello.
429 erreur de limitation de débitAttendez l’heure de réinitialisation renvoyée avant de réessayer. REST et MCP utilisent le même quota d’intégration.
Outil manquantVérifiez les périmètres de la clé avec whoami ; les outils indisponibles sont volontairement omis de la découverte.

Pour les champs des enregistrements, la pagination, le comportement des traitements par lot et les enveloppes d’erreur, consultez la référence de l’API Scoutello.

Planification de projet connectée​

Créez un projet, puis ses jalons, puis les tâches et les protocoles à l’aide d’identifiants externes d’intégration stables. L’accès aux nouveaux jalons nécessite milestones.read/milestones.write ; accordez members.read pour rechercher les membres pouvant être assignés. Les identifiants existants ne bénéficient pas automatiquement de permissions élargies. Après avoir effectué une rotation ou accordé l’accès, actualisez la découverte des outils et inspectez whoami.

Utilisez les identifiants client des membres pour assignedContacts des projets/jalons, et les identifiants utilisateur pour assignedScoutelloUserIds des tâches ou ownerScoutelloUserId des opportunités. Les références de tâches/protocoles acceptent projectScoutelloId ou projectExternalId, ainsi que les paires équivalentes de jalon/opportunité. Les liens limités au jalon déduisent le projet ; les incohérences rejettent l’élément du lot. Les participants au projet sont ajoutés ou mis à jour sans supprimer les entrées omises.

Les protocoles prennent en charge les notes de projet/jalon sans contact ainsi que le statut draft/final. L’import de ce travail connecté est silencieux et n’envoie jamais de communications. Les outils de liste exposent les mêmes filtres REST propres à chaque entité pour le projet, le statut, l’affectation et l’échéance. Transmettez les filtres exacts, notamment updatedSince, à chaque page parcourue avec un curseur. Consultez la référence de l’API pour connaître le contrat complet et la sémantique des valeurs nulles ou omises.

Validez chaque lot dépendant, appliquez-le, inspectez chaque résultat et relisez les enregistrements avant de considérer le peuplement comme terminé. Une simulation ne peut pas résoudre les parents qui n’existent que dans une autre simulation. Lors d’une nouvelle tentative pour un lien initial ambigu avec scoutelloId, recherchez d’abord par identifiant externe ; les identifiants d’amorçage ne peuvent pas être rejoués une fois le lien créé.

Instructions de l’agent pour les projets commerciaux​

Chaque contact créé ou réutilisé pour un projet commercial doit référencer explicitement ce projet à l’aide de projectScoutelloId ou projectExternalId dans contacts_batch_upsert. Mentionner un projet dans des notes ou un identifiant externe ne constitue pas une appartenance. Les écritures de contact avec des références de projet nécessitent également projects.write. Relisez le contact avec contacts.read et projects.read, puis vérifiez projectParticipations ; préservez les appartenances et groupes existants. Les contacts génériques hors projet ne nécessitent pas de référence de projet.

Conservez les entreprises et les personnes vérifiées dans des contacts distincts. Liez une personne à l’entreprise avec companyScoutelloId ou companyExternalId, et pas uniquement avec companyName. Les modifications du contact, de la relation avec l’entreprise et de l’appartenance sont atomiques pour chaque élément du lot ; les références non valides ne laissent aucun contact partiellement créé. N’inventez pas de personnes et n’appliquez pas de balises de provenance.

Préparez les e-mails sortants avec mail_drafts_batch_upsert, jamais sous forme de corps de protocole. Accordez explicitement les nouveaux périmètres mail-drafts.read et mail-drafts.write ; la préparation nécessite également contacts.read et projects.write. Les identifiants existants ne reçoivent automatiquement aucune nouvelle permission. Utilisez un identifiant externe stable, expectedVersion: 0 pour la création, des références explicites au projet et au contact, l’identifiant utilisateur d’une personne approbatrice acceptée, ainsi qu’un périmètre d’expéditeur organization ou personal configuré. Ne devinez jamais l’adresse d’un destinataire ni la configuration d’un expéditeur.

Conservez les recherches dans content.notes ; seuls content.subject et content.body constituent le contenu sortant. La création d’un brouillon garantit que le contact participe au projet. Les mises à jour doivent utiliser la version renvoyée par la dernière lecture ; les brouillons examinés ou distribués refusent toute modification. Les nouvelles tentatives identiques renvoient le brouillon d’origine sans créer une autre demande d’examen. Relisez son reviewUrl, draftVersion, contentHash, son statut d’approbation/distribution et son éventuel mailScoutelloId.

Seule la personne humaine désignée peut approuver et envoyer le contenu depuis l’écran d’examen existant. Les intégrations ne peuvent ni approuver, ni distribuer, ni envoyer, même avec un accès d’écriture aux brouillons. Préservez les protocoles d’origine lors de la conversion d’anciens brouillons et établissez des références croisées vers les remplacements. Les échecs de distribution en file d’attente ou ambigus nécessitent une investigation, jamais un nouvel envoi automatique.

Préparation des publications sociales​

Accordez social-channels.read, social-posts.read, social-post-drafts.read et social-post-drafts.write si nécessaire. members_list (members.read) peut trouver les identifiants des personnes chargées de la révision. Les outils sociaux sont proposés uniquement lorsque leur portée est accordée :

PortéeOutils
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

Consultez les capacités des canaux et l’historique créé par Scoutello, importez les fichiers, puis envoyez des variantes complètes pour chaque canal avec une personne chargée de la révision nommée. Les outils d’import renvoient des instructions HTTP PUT : transférez les octets du fichier original en dehors de MCP, puis finalisez l’import avec { "assetId": "..." }. N’intégrez pas de fichiers encodés en base64 dans les arguments des outils.

Utilisez expectedVersion: 0 pour les nouveaux brouillons et la version actuelle pour les révisions en attente. mode: "validate" n’effectue aucune écriture. L’outil renvoie l’URL de révision ; seule une personne utilisant le tableau de bord peut approuver la publication ou la planification. Aucun outil MCP ne permet d’approuver, de publier, d’annuler ou de supprimer une publication. Consultez régulièrement les outils de brouillons et d’historique pour suivre l’approbation, les motifs de rejet et les résultats de diffusion par canal. Les brouillons révisés nécessitent un nouvel identifiant externe pour toute proposition ultérieure.

Consultez publications sociales à réviser pour découvrir des exemples de saisie, les limites d’import, la pagination et le comportement en cas de révision tardive.