Aller au contenu
Base de connaissances

Interface MCP

Askalot prend en charge le Model Context Protocol (MCP), un standard ouvert qui permet aux assistants IA d’interagir directement avec la plateforme. Des agents IA peuvent ainsi créer des enquêtes, gérer des campagnes, dérouler des questionnaires et analyser les résultats au fil d’une conversation en langage naturel.

MCP est un protocole standardisé qui permet à des systèmes d’IA comme Claude d’utiliser des outils et des sources de données externes. Avec l’interface MCP d’Askalot, vous pouvez :

  • Automatiser vos processus d’enquête : créer des projets, des questionnaires et des campagnes au fil de conversations avec l’IA
  • Exécuter des enquêtes par programmation : parcourir le déroulé d’un questionnaire et soumettre des réponses
  • Gérer les répondants : importer, organiser et affecter des cibles d’enquête aux campagnes
  • Interroger le journal d’audit : suivre les modifications et garantir la conformité
  • Consulter la documentation : les agents IA peuvent lire la documentation de la plateforme pour se mettre en contexte
https://portor.<tenant>.askalot.io/mcp

Remplacez <tenant> par le nom de tenant de votre organisation.

Ce connecteur est destiné à vous et à votre équipe. Les répondants ne s’y connectent jamais : une campagne qui propose l’assistant IA fournit à chaque répondant un connecteur distinct, https://portor.<tenant>.askalot.io/respond/mcp, auquel il accède avec un code d’association affiché sur sa page d’enquête. Ce connecteur ne donne accès qu’à sa propre enquête. Voir Auto-entretien assisté par l’IA.

L’interface MCP s’authentifie par OAuth 2.1, et non par un jeton API que vous colleriez. Au premier appel d’outil, Portor renvoie 401 avec une indication de découverte OAuth, et votre client MCP (par exemple le plugin Askalot pour Claude Code) vous guide dans une connexion par navigateur auprès du fournisseur OIDC de la plateforme. Le client conserve ensuite les jetons d’accès et de rafraîchissement obtenus et envoie le jeton d’accès dans Authorization: Bearer à chaque appel : vous ne manipulez jamais vous-même la valeur du jeton porteur.

Configurer le point de terminaison (URL uniquement) :

Seule l’URL du serveur est à configurer. Le plugin Askalot la lit dans la variable d’environnement ASKALOT_MCP_URL ; une simple entrée .mcp.json porte la même URL et rien d’autre, sans champ de jeton :

{
"mcpServers": {
"askalot": {
"type": "http",
"url": "https://portor.<tenant>.askalot.io/mcp"
}
}
}

Se connecter (première utilisation) :

  1. Faites pointer le client vers votre tenant (export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp).
  2. Déclenchez n’importe quel outil MCP. Le client ouvre votre navigateur sur le point de terminaison /authorize de Portor, qui redirige vers la connexion OIDC de la plateforme.
  3. Connectez-vous. Au-dessus du formulaire, la page de connexion indique l’application qui fait la demande et l’adresse à laquelle votre accès sera transmis ; ne poursuivez que si vous avez lancé cette connexion depuis cette application. Le client échange le code contre des jetons et relance l’appel initial.
  4. L’échange dans le navigateur n’a lieu qu’une fois ; le jeton de rafraîchissement est ensuite échangé de manière transparente.

Votre session MCP se trouve toujours dans une seule organisation à la fois, son organisation active, et chaque appel d’outil est résolu dans celle-ci. Projets, questionnaires, campagnes, répondants et jeux de données sont tous rattachés à une organisation : c’est donc l’élément le plus important à connaître pour savoir où un outil cherche.

Point de départ. Une nouvelle session arrive dans votre organisation d’origine, celle à laquelle votre compte appartient. Aucun choix ne vous est demandé à la connexion.

La consulter. list_organizations renvoie toutes les organisations dans lesquelles la session peut agir, indique laquelle est active et signale celles qui sont scellées. Cette liste est exactement celle que vous propose le menu Changer d’organisation dans le navigateur ; si vous n’appartenez qu’à une organisation, la liste s’arrête là et il n’y a rien à gérer.

En changer. switch_organization déplace la session vers une autre organisation de cette liste. Tous les appels suivants sont résolus dans la nouvelle, et le changement est conservé : si vous redémarrez votre client MCP, vous reprenez là où vous en étiez. Le tenant est fixé à la connexion et ne change jamais ; changer d’organisation ne vous déplace donc qu’entre les organisations d’un même tenant.

Pouvoir entrer n’est pas pouvoir agir. La liste contient les organisations dont vous êtes membre ; ces adhésions sont accordées et retirées par un administrateur, jamais par la session elle-même (la liste d’un opérateur Askalot comprend toutes les organisations du tenant). L’adhésion permet à la session d’y entrer ; les outils qu’elle peut y utiliser dépendent de vos rôles dans cette organisation, et un rôle détenu ailleurs ne s’y applique pas. Dans une organisation dont vous êtes membre sans y avoir de rôle, la liste des outils se réduit aux outils de session (list_organizations, switch_organization, list_toolsets, get_my_entitlements et vos paramètres de modèle) jusqu’à ce qu’un administrateur vous y attribue un rôle ; vous pouvez donc toujours en ressortir. Si un administrateur vous retire de l’organisation où se trouve la session, la connexion prend fin ; reconnectez-vous et la nouvelle session démarre dans votre organisation d’origine.

Certaines organisations sont scellées : une démonstration soignée, ou les données d’un ancien client conservées pendant leur durée de conservation. list_organizations les signale, ce qui vous permet de le savoir avant d’agir.

Ce qui est scellé, c’est le dossier de recherche de l’organisation : ses projets, questionnaires, campagnes, répondants, viviers, enquêtes, jeux de données et articles de recherche. La lecture n’est pas affectée : lister et récupérer tous ces éléments fonctionne toujours, de même que les outils de documentation et de bibliothèque méthodologique. Les outils d’audit gardent leurs règles habituelles (voir Audit et conformité). Les créations, modifications et suppressions sont refusées avec org_sealed. Chaque outil déclare s’il lit ou s’il écrit, et c’est cette déclaration qui détermine le refus : la frontière est donc une propriété de l’outil, et non une supposition fondée sur son nom.

Essayer un instrument reste possible, car un aperçu ne modifie rien dans le dossier. create_survey appelé sans campagne lance un aperçu plutôt qu’une enquête, et get_survey_current_item, submit_survey_response et finish_survey permettent de le parcourir : vous pouvez ainsi relire un questionnaire de bout en bout dans une organisation scellée. Si vous indiquez une campagne à create_survey, l’appel est refusé : ce parcours serait un cas réel, et les cas réels entrent dans le jeu de données.

list_organizations et switch_organization continuent tous deux de fonctionner dans une telle organisation : une session peut donc toujours voir où elle peut aller ailleurs, et en sortir.

Le scellement désactive aussi les jetons API de cette organisation : vous ne pouvez pas en générer, et un jeton existant cesse de fonctionner. La connexion OAuth décrite plus haut n’est pas concernée.

Askalot effectue pour vous trois types d’appels IA, et chacun choisit séparément son fournisseur et son modèle : l’embedding (fixé au modèle local de la plateforme : l’indexation et la recherche doivent utiliser le même, il n’est donc pas configurable), le LLM direct (une complétion brute unique : extraction de mots-clés lors d’une recherche documentaire, et passe d’extraction lors de l’ingestion d’un document) et le raisonnement, qui fait tourner les agents et comporte un niveau high / medium / low.

get_model_configuration indique ce qui s’applique à votre propre compte et, pour chaque emplacement, d’où provient la valeur :

Source Signification
user vous l’avez choisie
org héritée de votre organisation
platform valeur par défaut d’Askalot (emplacement d’embedding uniquement)
mixed le fournisseur et le modèle proviennent de sources différentes
unconfigured rien n’est défini, et il n’existe pas de valeur par défaut de la plateforme

L’emplacement LLM direct et chaque niveau de raisonnement affichent unconfigured tant que vous ou votre organisation n’avez pas choisi de fournisseur, ce qui dissipe une confusion fréquente : ces emplacements n’ont volontairement aucune valeur par défaut de la plateforme, car les appels sont facturés sur votre propre compte fournisseur. Une recherche documentaire ou une ingestion refusée avec « requires an LLM provider — none is configured », ou un agent qui vous demande de configurer un fournisseur, correspond à cet état, et non à une clé défectueuse. Un niveau de raisonnement non configuré vaut null dans effective_config.

update_model_configuration modifie vos propres emplacements. L’outil fusionne : si vous indiquez direct_llm, vos niveaux de raisonnement restent inchangés ; si vous indiquez reasoning: {"high": …}, medium et low ne sont pas touchés. Passez null pour un niveau, ou clear_direct_llm: true, pour rendre un emplacement à la valeur de votre organisation. Les trois niveaux de raisonnement doivent finir sur un même fournisseur, et un niveau non défini compte comme une incohérence : une première écriture doit donc nommer les trois. Définir high seul est refusé, car medium et low resteraient non définis. Pour la même raison, effacer le raisonnement lorsque votre organisation n’en définit aucun implique de passer null pour les trois niveaux à la fois.

direct_llm et reasoning acceptent chacun anthropic_api ou bedrock. Demandez à get_model_configuration les valeurs acceptées et le modèle par défaut de chaque fournisseur plutôt que de les deviner ; une écriture refusée ne modifie rien et indique ce qui n’allait pas.

L’emplacement LLM direct et les niveaux de raisonnement forment chacun un panneau doté d’une case Toujours utiliser le dernier modèle, cochée sauf si vous l’avez décochée. Tant qu’elle est cochée, Askalot maintient les emplacements du panneau sur le Sonnet le plus récent (LLM direct) ou sur Opus / Sonnet / Haiku (high / medium / low), et ne change de modèle qu’après la réussite d’un appel de test avec l’identifiant de cet emplacement ; le fonctionnement est décrit dans Fonctions d’IA et choix des modèles. Avec les outils :

  • get_model_configuration renvoie auto_latest (par panneau, direct_llm et reasoning : si la case est cochée) et auto_status (par emplacement : date de la dernière vérification, résultat et dernier modèle dont l’appel de test a échoué). Les résultats possibles sont ok, no_newer_model, pending_verification, no_credential, catalog_unreadable, session_expired, ou le motif de refus renvoyé par l’appel de test lui-même.
  • Dans update_model_configuration, nommer un model_id pour un emplacement quelconque d’un panneau constitue un choix manuel : la case de ce panneau se décoche dans la même écriture, et l’autre panneau n’est pas touché. Ne nommer qu’un fournisseur pour un panneau dont la case est cochée (direct_llm={"provider": "bedrock"}, ou chaque niveau de raisonnement sous la forme {"provider": …}) remplit ses emplacements avec le modèle le plus récent de la famille de chaque emplacement proposé par ce fournisseur, laisse la case cochée et marque les emplacements pour un test lors de la prochaine vérification. La réponse inclut l’auto_latest qui en résulte.
  • L’outil ne recoche jamais une case ; cela se fait depuis la page de profil.

Les deux outils n’agissent que sur votre compte. Les mêmes paramètres figurent dans la section Modèles IA de votre page de profil, et toute modification, par l’une ou l’autre voie, est consignée dans le journal d’audit.

Le serveur MCP est l’une des deux surfaces qui exposent les mêmes fonctionnalités, et il ne peut pas vous signaler que vous avez choisi la mauvaise : la mauvaise voie est lente et coûteuse en contexte, pas une erreur.

  • MCP convient à une action sémantique unique, à une requête, ou à tout ce qui demande le jugement du serveur. La plupart du travail se fait ici.
  • REST (https://portor.<tenant>.askalot.io/api/v1) convient au travail en masse et à tout ce dont la charge utile ou le résultat est volumineux. Bouclez et filtrez hors de votre contexte, et n’en gardez qu’un résumé.

Quel identifiant : cela dépend de qui appelle. Le jeton d’accès OAuth qui authentifie votre session MCP est accepté sur /api/v1 sous la forme Authorization: Bearer <token>. Un jeton d’accès personnel (PAT) se place plutôt dans l’en-tête X-Api-Token, jamais en Bearer ; voir Authentification.

  • Un programme qui détient son propre jeton (un agent SDK qui gère sa session OAuth) peut le réutiliser sur REST. Il a déjà l’identifiant en main, et une session représente une seule identité sur les deux voies.
  • Le code que vous générez pour un bac à sable, ou tout ce qui survit au tour, utilise un PAT. Ce n’est pas une préférence : un bac à sable ne détient aucun identifiant propre lui donnant accès à cette API. Un PAT est en outre révocable séparément, ce qui n’est pas le cas d’un jeton de session.
  • Un modèle qui pilote un client de chat ne voit jamais le jeton : c’est le client qui le détient. Si vous écrivez du code, vous êtes dans le cas précédent.

Des points faciles à comprendre à l’envers :

  • bulk_create_respondents est plafonné à 100 par appel sur les deux voies. REST valide les mêmes entrées : 500 répondants représentent cinq appels dans les deux cas. REST l’emporte sur les allers-retours et le contexte, jamais sur le volume par appel.
  • Les verbes de tâche du pipeline code_open_ends et derive_silver sont réservés à MCP. Inutile de chercher un équivalent REST.
  • Les jeux de données ne sont pas réservés à MCP. list_datasets, get_dataset, delete_dataset et export_dataset ont tous des routes sous /api/v1/datasets, et lister ou exporter est précisément le genre de travail à gros résultat pour lequel REST existe.
  • Un contenu volumineux est renvoyé sous forme de lien. export_dataset, ainsi que get_qml_content au-delà de 32 Ko, renvoient un download_url signé de courte durée ; récupérez-le en HTTPS ordinaire.
  • Un enregistrement QML nomme la version à partir de laquelle il a été écrit. Lisez avec get_qml_content, puis passez son version_id comme base_version_id à save_qml_file ou finalize_upload. Après un enregistrement, nommez le version_id que cet enregistrement a renvoyé. En cas d’overlap, relisez et réappliquez votre modification ; ne renvoyez jamais le même contenu. Détails : Outils de questionnaire.
  • Interrogez l’état de la tâche plutôt que de boucler. Sans bac à sable de code, n’écrivez pas à la main des centaines d’appels d’outils successifs : lancez la tâche et interrogez get_task_status avec un identifiant de tâche, ou get_dataset pour une étape de jeu de données.

La surface complète compte plus de 120 outils, bien plus qu’il n’en faut sous les yeux pour un même travail de recherche. Une connexion peut nommer les domaines qu’elle souhaite, dans l’URL :

https://portor.<tenant>.askalot.io/mcp?toolsets=analysis,campaign

Les valeurs sont des noms d’ensembles d’outils séparés par des virgules. Une connexion qui n’en nomme aucun obtient tout : c’est le comportement par défaut, et il le reste.

Neuf ensembles d’outils peuvent être filtrés ainsi :

Ensemble Contenu
project Les projets et leurs propriétaires
questionnaire Les questionnaires et le cycle de vie QML
sampling Répondants, viviers et stratégies d’échantillonnage
campaign Les campagnes et leur configuration
fielding Enquêtes, invitations, enquêteurs, déroulé des réponses
analysis Lots, jeux de données et pipeline Bronze/Silver/Gold
documents Vos documents de référence importés
methodology La bibliothèque partagée de méthodologie d’enquête
audit Le journal d’audit

Huit autres sont admis sur chaque connexion, quoi que vous nommiez, car les retirer empêcherait un agent de corriger sa propre trajectoire : vos outils de session et d’organisation, l’historique de conversation, les droits d’accès, la documentation, l’outil list_toolsets lui-même, l’article de recherche, les outils composites ci-dessous, et get_task_status, si bien qu’un outil composite lancé sur une connexion restreinte peut toujours être interrogé depuis celle-ci.

Deux choses que ce mécanisme n’est pas, et qu’il vaut mieux préciser :

  • Ce n’est pas une frontière d’autorisation. Vous choisissez votre propre URL : nommer un ensemble d’outils n’exclut personne de quoi que ce soit. Ce que vous avez le droit de faire dépend de votre formule d’abonnement, de votre rôle et de la propriété des projets, que ce mécanisme ne modifie en rien. Il restreint ce qui est devant vous, pas ce que vous pouvez faire.
  • Ce n’est pas un rôle. Le paramètre n’accepte que ces noms d’ensembles d’outils ; il n’existe pas de raccourci ?toolsets=analyst.

Appelez list_toolsets à tout moment pour voir chaque ensemble d’outils, les outils qu’il contient, ce que votre connexion a nommé et les noms qu’elle n’a pas reconnus. Si vous appelez un outil exclu de votre connexion, le refus nomme l’ensemble qui le contient et le paramètre d’URL qui l’admettrait : une erreur d’estimation se rattrape donc sans relire cette page.

Changer de périmètre implique de se reconnecter, puisqu’il figure dans l’URL de connexion. Cette fonctionnalité est propre au transport HTTP ; une connexion stdio n’a pas d’URL et n’est jamais restreinte.

Trois séquences courantes sont chacune disponibles sous forme d’un outil unique. Ce ne sont pas des raccourcis qui sautent des étapes : chaque étape est le même outil que vous appelleriez à la main, qui écrit les mêmes enregistrements et laisse la même trace d’audit :

Un appel Ce qu’il exécute
prepare_campaign_fielding Stratégie d’échantillonnage → vivier de répondants → affectation du vivier → publication de la version du questionnaire → création des enquêtes
simulate_campaign_responses Création des enquêtes → génération de réponses synthétiques
run_bundle_pipeline Extraction Bronze → Silver (codage + pondération) → Gold

Trois points à connaître avant de les utiliser :

  • prepare_campaign_fielding s’arrête avant l’envoi des invitations. Il n’envoie jamais rien ; cela reste un appel distinct et délibéré à send_campaign_invitations, que vous effectuez après avoir examiné ce que la chaîne a construit. Un e-mail ne peut pas être rappelé.
  • Si une chaîne s’arrête en cours de route, ce qu’elle a déjà construit reste en place. Rien n’est annulé. La réponse nomme l’étape dans stopped_at_step ; une valeur non nulle signifie que la chaîne n’est pas allée au bout, et vous reprenez à partir de là avec les outils individuels. run_bundle_pipeline signale un arrêt dans son enveloppe {success: false, error, detail} ; les deux autres renvoient leur résultat habituel avec error et detail renseignés et sans clé success.
  • Une chaîne vérifie toute la séquence d’emblée. Si votre abonnement ne couvre pas une étape ultérieure, vous en êtes informé avant toute construction, plutôt que de recevoir un résultat à moitié terminé.

simulate_campaign_responses et run_bundle_pipeline renvoient un identifiant de tâche à interroger avec get_task_status. run_bundle_pipeline indique l’étape atteinte par son exécution et, une fois terminée, le jeu de données de chaque étape ; simulate_campaign_responses renvoie la même tâche de remplissage que l’outil brut mass_fill_surveys, si bien que son interrogation rend compte de la progression plutôt que des étapes.

L’interface MCP propose des outils regroupés par fonctionnalité.

Outil Description
list_organizations Liste les organisations vers lesquelles cette session peut basculer, en indiquant l’organisation active et en signalant celles qui sont scellées
switch_organization Change l’organisation active de la session ; tous les appels suivants sont résolus dans celle-ci
Outil Description
list_projects Liste tous vos projets
get_project Renvoie le détail d’un projet
create_project Crée un nouveau projet
add_project_owners Ajoute des utilisateurs comme propriétaires du projet (les cibles doivent être membres de l’organisation du projet)
remove_project_owners Retire des utilisateurs de la propriété du projet (même règle d’adhésion)
Outil Description
list_questionnaires Liste tous les questionnaires
get_questionnaire Renvoie le détail d’un questionnaire
create_questionnaire Crée un questionnaire à partir de contenu QML ou d’un modèle de la bibliothèque (template, copié dans la langue language, les autres langues de la bibliothèque devenant des traductions) ; avec du contenu, il peut aussi recevoir l’inventory à partir duquel ce contenu a été généré, stocké avec la version 1 (un inventaire non valide fait échouer toute la création)
list_questionnaire_templates Liste la bibliothèque de modèles de questionnaires dans l’une de ses langues (language ; la vôtre par défaut, avec l’anglais signalé par language_fallback lorsque la bibliothèque ne propose pas la vôtre), par catégorie et avec une recherche sur le nom et la description
rename_questionnaire Renomme un questionnaire (son adresse ne change pas)
delete_questionnaire Supprime un questionnaire de manière réversible
restore_questionnaire Restaure un questionnaire supprimé récemment
list_qml_files Liste les questionnaires QML de l’organisation
inspect_qml_file Résumé rapide de la version courante d’un questionnaire
preview_qml_item Affiche un item du questionnaire tel que le voit un répondant ; un hôte qui affiche les MCP Apps présente ses vrais contrôles dans un panneau en lecture seule
get_qml_content Récupère le QML courant d’un questionnaire et son version_id, la base que nomme un enregistrement (renvoie un lien de téléchargement de courte durée au lieu du contenu au-delà de 32 Ko)
validate_qml_file Lance la validation SMT Z3 sur la version courante d’un questionnaire (atteignabilité, cohérence)
qml_quality_report Calcule le tableau de bord de qualité de conception D2–D8 de la version courante d’un questionnaire
save_qml_file Enregistre du QML écrit à partir d’une version que vous nommez (base_version_id, issu de get_qml_content) : fusionné avec un enregistrement plus récent portant sur d’autres lignes, refusé comme overlap sur les mêmes lignes. Ne bloque jamais sur un brouillon invalide (un contenu de plus de 32 Ko est refusé ; utilisez la procédure de téléversement ci-dessous)
request_upload_url / finalize_upload Procédure en deux étapes pour enregistrer un contenu QML dépassant la limite de 32 Ko de save_qml_file ; finalize_upload nomme lui aussi base_version_id
request_import_upload_url Obtient un lien à usage unique pour téléverser un questionnaire imprimé (PDF ou Markdown) dans un projet en vue de son import ; envoyez-y le fichier par PUT
import_questionnaire Importe le fichier téléversé comme nouveau questionnaire en brouillon. Long et coûteux : il s’exécute sur votre propre fournisseur IA et compte dans votre limite mensuelle d’imports. Les réponses remplies sur la source sont écartées et le fichier téléversé est supprimé. Renvoie un task_id pour get_task_status. Nécessite le rôle Concepteur ou Gestionnaire (ou un opérateur) et un accès en écriture au projet
get_questionnaire_inventory Lit l’inventaire à partir duquel un questionnaire a été construit : la version qu’il décrit, chaque numéro de question imprimé avec son identifiant d’item, et les contrôles ajoutés plutôt qu’imprimés (invented), avec le rapport d’import
get_questionnaire_import_source Lit, en Markdown, la source qu’un import PDF a lue : ce qui a été trouvé et retiré (réponses, en-têtes et pieds de page courants, numéros de page imprimés), puis des pages entières depuis from_page jusqu’à environ max_chars (32 000 par défaut), avec next_page pour l’appel suivant. Chaque page commence par un repère indiquant sa page dans le fichier, le numéro imprimé dessus et si elle a été lue par le texte ou par la vision ; les numéros de page de l’inventaire sont ceux du fichier. Un questionnaire qui n’a pas été importé d’un PDF renvoie import_source_not_found
list_qml_translations Pour chaque langue, indique si la traduction d’une version est complète, quels textes ne sont pas traduits, et si elle est figée ou modifiée à la main
get_qml_translation La traduction d’une version dans une langue, avec chaque texte source à partir duquel rédiger et le updated_at que nomme un enregistrement
save_qml_translation Enregistre du texte traduit pour une langue (partiel, fusionné avec ce qui est stocké ; nomme base_updated_at). Texte uniquement : les identifiants ou codes inconnus et les listes positionnelles partielles sont refusés
delete_qml_translation Supprime la traduction d’une version dans une langue (refusé une fois figée)
publish_qml_file Publie un questionnaire dans une campagne : valide formellement et fige la version exacte (le seul point de passage contrôlé)
move_qml_to_project Déplace un questionnaire vers un autre projet (historique des versions conservé)
unpublish_qml_file Supprime un questionnaire de manière réversible en conservant l’historique de ses versions (bloqué s’il existe des campagnes actives)

Référence des paramètres : paramètres, schémas de retour, cycle de vie QML, structure de la sortie Z3

Outil Description
list_indexed_documents Liste tous les documents indexés pour la recherche sémantique par l’IA, chacun avec sa clé de document (par exemple projects/<project-id>/report.pdf)
get_document_summary Renvoie le résumé Markdown stocké d’un document, désigné par sa document_key
get_document_chunk Récupère un fragment précis d’un document indexé (document_key, chunk_index)
search_document_chunks_by_keyword Recherche des fragments de documents indexés par mot-clé, éventuellement limitée à des document_keys
Outil Description
read_paper Lit l’article de recherche d’un projet : les chapitres assemblés, avec le jeton de modification courant de chaque unité
edit_paper_unit Remplace un passage exact dans une unité de l’article, en laissant tout le reste inchangé à l’octet près
read_paper_translation Lit les traductions de l’article dans une langue : sans unité, l’état de chaque unité (à jour, en retard, manquante) et ses jetons de modification ; avec une unité, son texte source et sa traduction côte à côte
edit_paper_translation Écrit la traduction d’une unité dans une langue, ancrée comme edit_paper_unit ; une traduction faite à partir d’une source plus ancienne est remplacée entièrement

L’article est rédigé dans sa langue source (l’anglais). Une traduction est un texte distinct placé à côté de chaque unité, présenté aux lecteurs qui lisent l’article dans cette langue, et n’est jamais écrite dans l’unité source. La compétence (skill) translate-paper du plugin Askalot guide un agent tout au long d’une passe de traduction.

Outil Description
list_campaigns Liste les campagnes (éventuellement par projet)
get_campaign Renvoie le détail d’une campagne
create_campaign Crée une nouvelle campagne
update_campaign Modifie les champs d’une campagne (nom, dates, statut, admission des volontaires, offre de l’assistant IA et ses textes)
delete_campaign Supprime une campagne
add_interviewers_to_campaign Ajoute des enquêteurs (utilisateurs ayant le rôle Enquêteur)
remove_interviewers_from_campaign Retire des enquêteurs d’une campagne
update_campaign_questionnaire Change le questionnaire affecté à une campagne
assign_pool_to_campaign Affecte un vivier de répondants à une campagne
get_campaign_pool Renvoie le vivier de répondants affecté à une campagne
send_campaign_invitations Envoie les e-mails d’invitation à l’enquête aux répondants

Les répondants ne sont pas ajoutés directement à une campagne : affectez un vivier de répondants avec assign_pool_to_campaign, puis bulk_create_surveys crée une enquête pour chaque répondant du vivier.

Référence des paramètres : paramètres, schémas de retour, opérations groupées, éligibilité aux invitations

Outil Description
list_respondents Liste tous les répondants (cibles d’enquête)
get_respondent Renvoie le détail d’un répondant
create_respondent Crée un nouveau répondant
update_respondent Met à jour les informations d’un répondant
delete_respondent Supprime un répondant
bulk_create_respondents Crée plusieurs répondants en une fois
bulk_delete_respondents Supprime des répondants selon un filtre (procédure en deux étapes avec dry_run)
generate_survey_access_token Émet un jeton de lien magique pour l’enquête d’un répondant
send_survey_invitation Envoie à un répondant une invitation à l’enquête par lien magique

Référence des paramètres : paramètres, schémas de retour, création en masse, données démographiques

Les viviers de répondants permettent d’organiser les répondants en groupes réutilisables pour les campagnes.

Outil Description
list_respondent_pools Liste tous les viviers de répondants
get_respondent_pool Renvoie le détail d’un vivier, y compris la liste des répondants
create_respondent_pool Crée un nouveau vivier de répondants
add_respondents_to_pool Ajoute des répondants à un vivier existant
remove_respondents_from_pool Retire des répondants d’un vivier
generate_pool_from_strategy Tire un vivier d’une stratégie d’échantillonnage à la taille demandée ; le vivier conserve ses paramètres de tirage
preview_pool_generation Prévisualise un tirage sans créer le vivier
plan_sample_size Lecture seule : dimensionne un tirage à partir des cibles d’objectif d’un projet (marge d’erreur ou puissance pour deux groupes, bilatéral, approximation normale), de l’éligibilité, du taux de réponse et de l’effet de plan ; renvoie le nombre de questionnaires complets nécessaires, le facteur de suréchantillonnage et le nombre de personnes à inviter, avec la révision des cibles enregistrées. Également POST /api/v1/projects/{project_id}/sample-size-plan
save_sizing_targets Enregistre la cible de chaque objectif dans l’article du projet, en nommant la révision que vous avez lue ; une révision obsolète constitue un conflit (REST 409). Également PUT /api/v1/projects/{project_id}/sizing-targets
refresh_pool_from_strategy Tire à nouveau un vivier existant avec les paramètres de tirage qu’il conserve
delete_respondent_pool Supprime un vivier de répondants

Référence des paramètres : paramètres, schémas de retour, gestion des doublons, génération à partir d’une stratégie

Les stratégies d’échantillonnage définissent des distributions démographiques cibles pour constituer des échantillons représentatifs de répondants. Une stratégie ne porte aucun paramètre de taille ni de sélection (ce sont des entrées de chaque tirage de vivier) : une même stratégie peut donc alimenter des viviers de n’importe quelle taille.

Outil Description
list_sampling_strategies Liste toutes les stratégies d’échantillonnage
get_sampling_strategy Renvoie le détail d’une stratégie, y compris ses facteurs
create_sampling_strategy Crée une stratégie avec des facteurs de répondants personnalisés
create_default_strategy Crée une stratégie avec les facteurs standard de genre et d’âge
update_sampling_strategy Met à jour une stratégie existante
delete_sampling_strategy Supprime une stratégie d’échantillonnage

Exemple : créer une stratégie d’échantillonnage personnalisée

AI Assistant: I'll create a sampling strategy targeting your demographics.
→ create_sampling_strategy(
name="Urban Millennials",
project_id="...",
factors=[
{"name": "Gender", "attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}},
{"name": "Age Group", "attribute_path": "age",
"target_distribution": {"25-34": 0.60, "35-44": 0.40}}
]
)
Strategy created! Now generating a representative pool...
→ generate_pool_from_strategy(strategy_id, pool_name="Urban Millennials Pool",
requested_size=200)

Référence des paramètres : paramètres, schémas de retour, schéma des facteurs, validation des distributions

Outil Description
list_users Liste les utilisateurs de votre organisation active (enquêteurs compris) ; appelez switch_organization pour voir les utilisateurs d’une autre organisation
get_user Renvoie le détail d’un utilisateur

Remarque : les enquêteurs sont des utilisateurs ayant le rôle interviewer. Ils sont gérés comme des utilisateurs, et non comme des répondants.

Pour les campagnes avec enquêteurs (utilisateurs ayant le rôle Enquêteur), gérez la répartition de la charge de travail :

Outil Description
assign_respondents_to_interviewer Affecte des répondants à un enquêteur donné (utilisateur)
unassign_respondents_from_interviewer Supprime des affectations d’enquêteur
get_interviewer_workload Affiche les répondants affectés et l’état d’avancement
get_unassigned_respondents Trouve les répondants pas encore affectés
Outil Description
list_surveys Liste les enquêtes (filtre par campagne ou par répondant)
create_survey Démarre une nouvelle session d’enquête
update_survey Met à jour le statut et l’état de déroulé d’une enquête (les entités liées sont immuables)
bulk_create_surveys Crée des enquêtes pour tous les répondants d’une campagne
bulk_delete_surveys Supprime des enquêtes selon un filtre (procédure en deux étapes avec dry_run)
get_survey_current_item Renvoie la question courante avec ses options intégrées
submit_survey_response Soumet une réponse et avance (étape suivante intégrée)
finish_survey Termine explicitement une enquête
mass_fill_surveys Met en file d’attente une tâche asynchrone d’arrière-plan qui remplit des enquêtes avec des réponses de test synthétiques (renvoie {task_id, status})
get_task_status Interroge une tâche asynchrone par son task_id : une exécution de mass_fill_surveys, une chaîne simulate_campaign_responses ou run_bundle_pipeline, ou une exécution d’import_questionnaire (les tâches de codage des jeux de données s’interrogent plutôt avec get_dataset)

Référence des paramètres : paramètres, schémas de retour, machine à états, modes de distribution, personas

Un lot associe un projet, un questionnaire et un sous-ensemble de campagnes à une chaîne linéaire de jeux de données Bronze → Silver → Gold. Les outils de lot gèrent cette association et portent le bilan de qualité du lot ; les outils de jeux de données exécutent chaque étape propre au lot : extraction, codage + pondération, affinage et export.

Outil Description
create_bundle Crée un lot de pipeline
list_bundles Liste les lots, éventuellement filtrés par projet
get_bundle Détail d’un lot, y compris les recettes de ses étapes (cibles de calage Silver, opérations Gold)
clone_bundle Copie en profondeur les jeux de données prêts et les recettes d’un lot dans une variante indépendante
delete_bundle Supprime un lot et sa chaîne de jeux de données
get_bundle_quality Le bilan de représentativité du lot (sélection, terrain, pondération, écart dû au terrain, réponse)
compare_bundle_quality Amélioration de Bronze à Silver au regard de la stratégie actuelle du lot
get_bundle_coding État du codage des questions ouvertes : les candidats que propose le jeu de données Bronze, le type de réponse retenu par l’analyste pour chacun (descriptif, nominal ou identifiant ; absent = non classé), la sélection de questions et, par question, les dimensions proposées, leurs catégories et celles qui sont sélectionnées
set_coding_selection Définit les unités de texte ouvert que le lot code (rôle Gestionnaire, utilisateur identifié requis) ; refuse une unité non classée ou de type identifiant, et aucun outil n’en classe
assign_bundle_strategy Affecte (ou retire) la stratégie d’échantillonnage courante du lot
set_calibration_targets Modifie les cibles de calage du lot, c’est-à-dire la spécification de pondération Silver, chacune raked (utilisée pour le calage) ou benchmark (seulement évaluée) ; chaque enregistrement vérifie les codes de réponse par rapport au questionnaire du lot
preview_calibration_targets_copy Prévisualise la copie des cibles de calage d’un autre lot dans celui-ci : celles qui conviennent (avec leur rôle) et celles qui ne conviennent pas, avec le motif ; n’écrit rien
list_datasets Liste les jeux de données de la chaîne d’un lot
get_dataset Renvoie le détail, les métriques et le statut d’un jeu de données : la surface bornée que les étapes du pipeline invitent à interroger
get_dataset_schema Renvoie le schéma des colonnes d’un jeu de données, ou seulement les noms de colonnes et types de contrôle, éventuellement restreint à des colonnes nommées
create_bronze_dataset Extrait le jeu de données Bronze d’un lot
code_open_ends (alias derive_silver) Code le texte des questions ouvertes, puis pondère selon les cibles de calage, ce qui produit le jeu de données Silver du lot
create_gold_dataset Affine le jeu de données Silver d’un lot en jeu de données Gold, à l’aide du catalogue d’opérations Gold
export_dataset Exporte un jeu de données prêt (CSV, XLSX, SPSS, Parquet, R, JSON)
delete_dataset Supprime un jeu de données

Référence des outils de lot : paramètres du cycle de vie et de la qualité des lots, schémas de retour

Référence des outils de jeux de données : paramètres des étapes, schémas de retour, formats d’export

Outil Description
query_audit_events Recherche dans le journal d’audit avec des filtres
get_entity_history Affiche l’historique complet de n’importe quelle entité
get_audit_stats Nombre d’événements par type d’entité

Ces trois outils ne lisent que votre tenant et votre organisation active. Pour lire le journal d’une autre organisation, basculez d’abord dans celle-ci. Les événements enregistrés sans organisation, comme les actions du système et des services, ne sont pas renvoyés.

Au sein de l’organisation, ce que vous voyez dépend de votre rôle :

Qui Ce que renvoient les outils d’audit
Administrateur (org_admin de l’organisation, ou opérateur Askalot) Le journal complet de l’organisation, y compris get_audit_stats
manager Vos propres actions, plus l’historique complet des projets, questionnaires, campagnes et enquêtes des projets dont vous êtes propriétaire
Tout autre utilisateur Vos propres actions uniquement

Demander les actions d’un autre utilisateur, ou l’historique d’une entité hors de votre portée, est refusé. get_audit_stats est réservé aux administrateurs, et une connexion qui n’agit pour aucun utilisateur ne lit aucun audit. Dans une organisation où chaque membre lit chaque projet, comme l’organisation publique Askalot Demo, le journal d’audit est réservé aux administrateurs : pouvoir lire la recherche ne donne pas le droit de lire qui a fait quoi, car les événements d’audit contiennent des informations telles que les adresses IP.

La visionneuse d’audit du navigateur applique les mêmes rôles, mais un opérateur Askalot et un utilisateur ordinaire y ont une vue plus large :

Qui Ce qu’affiche la visionneuse d’audit du navigateur
Opérateur Askalot (tenant_admin) Tous les événements du tenant, toutes organisations confondues
Administrateur de l’organisation (org_admin) Tous les événements de l’organisation active
manager Au sein de l’organisation active : vos propres actions, plus l’historique des projets, questionnaires, campagnes et enquêtes des projets dont vous êtes propriétaire
Tout autre utilisateur Vos propres actions uniquement, y compris vos connexions

Une connexion est enregistrée dans l’organisation où démarre la session, et une déconnexion ou un changement de mot de passe dans l’organisation où la session travaille : elles font donc partie du journal de cette organisation comme toute autre action.

Outil Description
list_documentation Liste la documentation disponible
get_documentation Charge un document précis
search_documentation Recherche dans la documentation par mot-clé

Les ressources donnent un accès en lecture seule aux données de la plateforme :

URI de ressource Description
repository://overview Statistiques et décomptes de la plateforme
repository://schema Relations et structure des entités
qml://files Les questionnaires QML de l’organisation
docs://primer Présentation de la plateforme
docs://qml-syntax Référence du langage QML
docs://getting-started Guide de démarrage rapide

D’autres ressources documentaires reflètent la base de connaissances (docs://guide, docs://glossary, docs://campaign-management, docs://survey-execution, docs://creating-surveys, docs://data-analysis, docs://quality-metrics).

AI Assistant: I'll help you set up a customer satisfaction survey.
1. First, let me create a project...
→ create_project("Customer Research 2026", "Annual satisfaction study")
2. Now I'll register your questionnaire...
→ create_questionnaire("CSAT Survey", qml_content, project_id)
3. Creating the campaign...
→ create_campaign("Q1 CSAT", project_id, questionnaire_id, admits_volunteers=false, offers_ai_channel=false)
4. Adding your respondent list...
→ bulk_create_respondents(100, generate_demographics=true)
→ create_respondent_pool("CSAT Sample", respondent_ids=[...])
→ assign_pool_to_campaign(campaign_id, pool_id)
→ bulk_create_surveys(campaign_id)
Your campaign is ready! 100 respondents have surveys waiting.
AI Assistant: I'll import your paper questionnaire into the project.
1. Getting an upload link for the PDF...
→ request_import_upload_url(project_id, "application/pdf")
PUT the file to upload_url with Content-Type: application/pdf
2. Starting the import (this takes a few minutes)...
→ import_questionnaire(project_id, upload_id, "visitor-survey.pdf")
→ get_task_status(task_id) # until completed or failed
3. Reading what it built...
→ get_questionnaire_inventory(result.questionnaire_id)
Each printed question number maps to its item id; the checks marked
invented were added and are worth reviewing before you publish.
4. Checking a question against what the import read (PDF only)...
→ get_questionnaire_import_source(result.questionnaire_id, from_page=12)

Un import refusé ne lance rien et indique ce qui permet de lever le refus : unsupported_type (seuls le PDF et le Markdown sont lus aujourd’hui), too_large, invalid_request, no_ai_slot (connectez une clé API Anthropic ou Amazon Bedrock, ainsi qu’un modèle LLM direct, dans Paramètres du profil) ou fair_use_exceeded (la limite mensuelle d’imports). Un import refusé nécessite un nouveau téléversement, car le fichier est supprimé dans tous les cas.

AI Assistant: I'll create a demographically balanced sample for your study.
1. Creating a sampling strategy with your target demographics...
→ create_sampling_strategy(
name="National Representative",
project_id,
factors=[
{"name": "Gender", "attribute_path": "gender",
"target_distribution": {"male": 0.49, "female": 0.51}},
{"name": "Age", "attribute_path": "age",
"target_distribution": {"18-34": 0.30, "35-54": 0.40, "55+": 0.30}}
]
)
2. Generating a pool that matches your targets...
→ generate_pool_from_strategy(strategy_id, pool_name="Q1 Sample Pool",
requested_size=500)
3. Assigning the pool to your campaign...
→ assign_pool_to_campaign(campaign_id, pool_id)
Done! Your campaign now has 500 respondents balanced to match
national demographics.
AI Assistant: I'll walk through the survey and show you each question.
→ create_survey(questionnaire_id, respondent_id)
→ get_survey_current_item(survey_id)
Question 1: "What is your age?"
Type: Integer input (18-100)
User: 35
→ submit_survey_response(survey_id, "q_age", 35)
→ get_survey_current_item(survey_id)
Question 2: "How satisfied are you with our service?"
Type: Scale (1-5)
...
AI Assistant: Let me distribute the 50 respondents among your 5 interviewers (Users with interviewer role).
→ get_unassigned_respondents(campaign_id)
Found 50 unassigned respondents
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_1, respondents[0:10])
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_2, respondents[10:20])
...
→ get_interviewer_workload(campaign_id, interviewer_user_1)
Assigned: 10 respondents
Completed: 0
In Progress: 0

Comprendre le modèle d’entités aide à travailler avec l’interface MCP :

Project
├── Questionnaire (owns a QML version chain)
└── Campaign
├── Respondents (survey targets)
├── Interviewers (Users with interviewer role, optional)
└── Surveys (individual sessions)

Chaque questionnaire appartient à un projet, et chaque utilisateur dispose d’un projet par défaut (is_default: true). Lorsqu’une demande ne nomme aucun projet, trouvez le projet par défaut avec list_projects et utilisez son identifiant.

  • Répondants : cibles d’enquête dotées de données démographiques. Les enquêtes qu’ils terminent déterminent l’avancement de la campagne. Ils accèdent aux enquêtes par des liens magiques (aucune authentification sur la plateforme n’est requise).
  • Enquêteurs (facultatifs) : utilisateurs ayant le rôle interviewer qui accompagnent les répondants dans leurs enquêtes. Ils disposent d’un identifiant de connexion à la plateforme et aident les répondants à remplir les enquêtes, sans les remplir eux-mêmes.

Les enquêteurs peuvent être affectés pour aider les répondants en face à face ou par téléphone. Lorsque des enquêteurs sont affectés, chaque enquête enregistre quel enquêteur a accompagné le répondant.

  • Les répondants sont des cibles d’enquête dotées de données démographiques (âge, genre, lieu). Ils n’ont pas de compte sur la plateforme.
  • Les utilisateurs sont des comptes de la plateforme servant à l’authentification et à la gestion. Les utilisateurs ayant le rôle interviewer peuvent accompagner des enquêtes.
  • Répondants et utilisateurs sont des entités distinctes. Les enquêteurs sont des utilisateurs, et non des répondants.

Les outils MCP renvoient des messages d’erreur structurés. Deux d’entre eux s’appliquent à toutes les catégories :

  • not_found : l’entité ne se trouve pas dans l’organisation active de la session. Le message nomme l’organisation dans laquelle la recherche a eu lieu ; voir Votre organisation active.
  • org_sealed : l’organisation active est scellée. Les lectures aboutissent ; ce refus ne vient jamais que d’un outil qui aurait modifié son dossier de recherche.

Les cas d’erreur détaillés sont documentés par catégorie :