Connecter un assistant IA avec MCP

Activity Messenger prend en charge le protocole MCP (Model Context Protocol), qui permet à un client IA externe compatible de découvrir et d'utiliser les actions AM autorisées pour votre organisation. Vous pouvez consulter des données, travailler avec des rapports, préparer des modifications et poursuivre les tâches prises en charge dans AM. Les modifications soumises à approbation exigent toujours votre révision dans Activity Messenger.

Avant la connexion

Il vous faut :

Un client MCP distant compatible avec Streamable HTTP et un jeton Bearer personnalisé.
Un utilisateur AM actif et confirmé, autorisé à utiliser l'assistant dans l'organisation.
Un jeton MCP généré par un opérateur autorisé pour cet utilisateur et cette organisation.

AM héberge MCP dans son application existante. Vous n'avez pas à installer un serveur MCP distinct. Les clients exigeant la découverte et le consentement OAuth ne peuvent pas encore utiliser cette intégration par jeton Bearer.

Le déploiement MCP ne crée aucun jeton et ne connecte aucun client automatiquement. Demandez la portée appropriée à un opérateur autorisé :

Lecture seule : consultations prises en charge, sans les outils de conversation ni les processus de modification.
Catalogue complet : toutes les actions actuellement autorisées et leurs outils de conversation, préparation, révision et espace de travail. L'opérateur doit générer ce jeton avec --allow-changes.

Un jeton complet n'accorde aucun rôle AM supplémentaire. Les autorisations courantes de l'utilisateur dans l'organisation et les modules restent applicables. Les jetons en lecture seule existants ne sont pas élargis automatiquement.

Configurer la connexion

Ajoutez un serveur MCP distant dans votre client compatible.
Choisissez Streamable HTTP et entrez cette URL en remplaçant l'espace réservé par l'identifiant de l'organisation associé au jeton :
```
https://activitymessenger.com/api/mcp/organization/<organization-id>
```
Conservez le secret dans le stockage protégé des autorisations Bearer du client. Si le client utilise un en-tête personnalisé, fournissez Authorization: Bearer <mcp-token>.
Connectez le client et laissez-le initialiser MCP et découvrir les outils. Les clients qui gèrent directement les en-têtes doivent envoyer Content-Type: application/json et accepter application/json, text/event-stream.

Ne placez jamais le secret dans l'URL ni dans une conversation ordinaire. Chaque connexion correspond à une organisation et à un utilisateur. Utilisez une connexion distincte pour une autre organisation.

Les jetons sont valides de 1 à 90 jours, avec 30 jours par défaut. Le secret est affiché une fois lors de sa création. Un opérateur autorisé peut révoquer un jeton; l'expiration ou la révocation bloque aussi la poursuite des approbations et exécutions natives liées.

Découvrir les actions disponibles

Le client découvre les outils avec tools/list. Il doit suivre nextCursor jusqu'à la fin; la première page ne représente pas la liste complète. Une page contient 15 outils par défaut et jusqu'à 50 sur demande.

Avec un jeton complet, utilisez discover_application_actions pour trouver les actions et get_application_action pour consulter les entrées exactes de l'action choisie. Les outils disponibles dépendent des autorisations courantes de l'utilisateur.

Le « catalogue complet » comprend les actions enregistrées et actuellement autorisées, y compris les tâches réalisées dans les éditeurs natifs AM. Plusieurs actions peuvent partager un outil MCP. Cela ne signifie pas que chaque fonction AM possède un outil de modification serveur dédié ni que les tâches d'éditeur peuvent terminer sans AM ouvert.

Consultez le catalogue complet des actions et outils pour les fonctionnalités enregistrées par module, avec noms des outils, entrées obligatoires, portée du jeton et exigences de révision.

Préparer et réviser une modification

Voici le processus habituel :

Le client appelle start_mcp_session avec votre demande. AM retourne les identifiants de conversation et de tour, un lien de révision am_url et une URL de téléversement.
Le client découvre l'action souhaitée, vérifie ses entrées et prépare la proposition avec l'outil natif ou prepare_application_action.
Le client appelle apply_assistant_draft pour cette proposition. Cela demande une révision humaine; cet appel n'approuve ni n'applique la modification à lui seul.
Ouvrez am_url et connectez-vous à AM avec l'utilisateur associé au jeton. Révisez la proposition réelle et approuvez-la ou refusez-la dans AM.
Le client consulte get_mcp_session pour l'état courant et le reçu de réalisation. Une réponse en file ou en attente ne prouve pas que la modification est terminée.

Par exemple, pour créer un cours puis son rappel, révisez d'abord le cours. Après sa création, le client utilise les véritables identifiants retournés pour préparer le rappel et demander sa propre révision.

Le jeton ne peut pas approuver sa propre proposition et ne connecte pas le navigateur. Chaque conversation MCP appartient au jeton précis, à l'utilisateur et à l'organisation; un autre jeton du même utilisateur ne peut pas la réutiliser.

Un tour externe actif bloque un autre tour dans le clavardage natif. Utilisez close_mcp_turn pour terminer un tour externe inactif, puis begin_mcp_turn pour la prochaine demande. Les approbations actives et les outils en cours doivent terminer leur propre processus.

Éditeurs, fichiers et rapports

Certaines actions passent à l'espace navigateur natif AM avec request_application_task. Ouvrez le lien AM retourné et gardez la page ouverte. Une réponse browser_required indique ce transfert nécessaire, pas la fin de la tâche. Les autorisations courantes et les confirmations natives restent applicables.

Pour les fichiers, le client envoie le fichier réel à upload_url, avec le même jeton Bearer et le champ multipart file. Les formats acceptés sont JPG/JPEG/PNG/GIF/WebP, PDF et XLS/XLSX, jusqu'à 10 Mio par fichier. Les téléversements sont privés et liés à la conversation. Joignez le jeton de fichier retourné au prochain message avec begin_mcp_turn; téléverser ne suffit pas à joindre ou utiliser le fichier. Les URL distantes et chemins serveur ne sont pas des entrées de fichier.

Les rapports peuvent retourner des identifiants de résultats enregistrés pour les graphiques. Un résultat contextuel volumineux fournit un tool_result_id; le client peut le lire avec read_mcp_result et suivre next_offset sans relancer l'action.

Dépannage

Certains outils manquent : terminez la pagination, vérifiez la portée du jeton et les autorisations courantes des modules. Les outils de conversation et de découverte des actions exigent un jeton complet.
La connexion retourne HTTP 401 : vérifiez le secret, l'organisation, l'expiration/révocation et l'état actif et confirmé du compte. HTTP 403 peut indiquer une autorisation refusée, une origine navigateur non autorisée ou une connexion sans HTTPS.
Une proposition reste en attente : ouvrez son lien AM, connectez-vous avec l'utilisateur du jeton et révisez-la. Consultez ensuite la conversation jusqu'à la fin du travail natif.
Une tâche navigateur attend : gardez la page de révision AM ouverte pour son espace natif.
Une requête est interrompue : les appels contextuels utilisent un am_call_id. Réessayez avec le même identifiant et les mêmes arguments. N'inventez pas un nouvel identifiant pour contourner une modification incertaine. Une répétition conserve le résultat initial; consultez la conversation pour les décisions et reçus ultérieurs.
Un résultat est trop volumineux : réduisez les filtres ou la pagination native, ou lisez le résultat enregistré lorsqu'un identifiant est retourné. Une lecture indépendante trop volumineuse n'a pas de résultat de conversation enregistré.

Les requêtes JSON sont limitées à 64 Kio en lecture seule et à 2 Mio avec un jeton complet. MCP autorise 60 requêtes par minute par IP et, par défaut, par jeton; les téléversements ajoutent une limite de 20 par minute par IP. HTTP 429 comprend Retry-After. Les dates suivent les règles natives du fuseau de l'organisation.