Passer au contenu principal

​
Scopes et autorisations par rôle

Le connecteur fonctionne avec les scopes didit:management et didit:verification. Un troisième scope, didit:staff, est annoncé mais ne concerne que les comptes du personnel Didit. Ces deux limites sont appliquées à chaque appel : le token contient les scopes que vous avez approuvés, et dans ce périmètre, votre rôle dans la console détermine ce que vous pouvez faire. L’accès effectif correspond à l’intersection des deux. Si vous n’approuvez que didit:verification, la surface de gestion reste fermée, même pour un OWNER. Chaque outil correspond à une autorisation du backend (read:sessions, write:workflows, delete:lists, etc. ; la référence des outils indique l’autorisation de chaque outil). Le serveur vérifie cette autorisation en amont, à partir des autorisations de l’organisation renvoyées par l’introspection du token, selon la valeur de MCP_PERMISSION_MODE : Le MCP ne va jamais au-delà de votre rôle. Un 403 sur un outil signifie que votre rôle ne dispose pas de cette autorisation, et non que la connexion entière a échoué.

​
Résolution inter-applications et organisation

L’API de gestion de Didit est délimitée par application (/organization/{org}/application/{app}/…). Le MCP résout le périmètre à votre place :
  • Une seule organisation et une seule application → résolues automatiquement. Vous n’avez jamais à transmettre d’identifiants.
  • Plusieurs applications → les outils inter-applications (didit_session_search, didit_transaction_search, didit_case_search, didit_vendor_user_search, didit_vendor_business_search, didit_workflow_search, didit_analytics) agrègent toutes les applications en un seul appel. Chaque ligne porte son organization_id / application_id.
  • Les outils de liste par application (didit_session_list, didit_transaction_list, didit_case_list, didit_vendor_user_list, didit_vendor_business_list, didit_workflow_list) couvrent automatiquement toutes les applications si vous n’en précisez aucune. Une demande simple comme « liste mes sessions » fonctionne donc même avec de nombreuses applications. Transmettez organization_id + application_id pour limiter la requête à une seule application.
Utilisez didit_context_get pour afficher en un seul appel toutes vos organisations et applications, avec leurs identifiants. Il indique aussi le mode de chaque application (live ou sandbox). Ne déduisez jamais l’environnement à partir du nom d’une application. didit_session_create accepte un sandbox_scenario sur les applications sandbox, pour des tests non facturés.

​
Contenu du catalogue hébergé

Le connecteur hébergé vous donne accès à 169 outils. Il liste aussi 17 outils Investigator, qui ne fonctionnent qu’une fois Investigator activé pour votre organisation. Deux autres outils, didit_org_top_up (paiement Stripe) et didit_org_reveal_application_api_key (secret brut), sont masqués dans le tools/list de tout appelant authentifié par OAuth. Les cinq outils de configuration de compte (didit_account_*) sont exclus des serveurs distants et refusent de s’exécuter sur ceux-ci, car un connecteur distant ne doit jamais recevoir d’identifiants en tant qu’arguments d’outil. Un serveur stdio local les conserve tous, soit 193 au total. Chaque outil listé porte des annotations MCP (readOnlyHint, destructiveHint, openWorldHint, un title) et un outputSchema. Il porte aussi un libellé _meta["anthropic/toolGroup"] qui nomme son domaine (Sessions, Workflows et Questionnaires, Transactions (AML), etc.). Des clients comme Claude s’appuient sur les annotations pour répartir les outils du connecteur en groupes en lecture seule, en écriture et destructifs.

​
Branches conditionnelles

Les workflows simples sont une liste linéaire de fonctionnalités. Pour la logique conditionnelle (refuser selon un statut, orienter selon un champ extrait, conditionner une étape à une correspondance, ajouter une demande de Document AI), le MCP s’appuie sur le graphe de nœuds de Didit (la même structure que le constructeur visuel de la console). Un graphe est { start_node, nodes } ; chaque nœud est une feature, une branch, un status (final), une action ou un webhook. Les règles de branche acceptent des opérateurs, dont fuzzy_match (champs de type chaîne, avec un seuil de similarité score de 0 à 100), sur des champs extraits comme kyc.extra_fields.profession. Un nœud de fonctionnalité DOCUMENT_AI demande des documents, par exemple un justificatif de fonds.

​
Modifier un workflow existant (recommandé)

Les workflows réels comportent des configurations de fonctionnalités volumineuses : une liste d’autorisation OCR documents_allowed peut dépasser 150 KB, sans compter les listes POA et les listes de pays associés aux numéros de téléphone. Évitez donc de lire l’intégralité du graphe puis de le renvoyer. Modifiez-le plutôt avec de petites opérations :
1

Localiser et inspecter

didit_workflow_search { workflow_id } retrouve le workflow dans toutes vos applications. didit_workflow_get_graph renvoie la structure, les grandes configurations étant résumées (la réponse ne déborde jamais ; passez include_config: true pour obtenir les valeurs brutes). didit_workflow_get_field_definitions liste les champs utilisables dans les branches ainsi que les opérateurs valides.
2

Modifier avec des opérations

didit_workflow_edit_graph prend quelques petites opérations : set_next, set_node, set_branches, merge_node_config. Le MCP récupère le graphe complet côté serveur, applique les opérations, valide le résultat, crée automatiquement un brouillon et l’enregistre. Vos listes d’autorisation sont conservées octet pour octet et ne transitent jamais par la requête. Si la validation échoue, la réponse renvoie applied: false (rien n’est enregistré).
3

Relire et publier

Le workflow reste un brouillon pouvant être examiné tant que vous ne le publish pas (dans la console ou via didit_workflow_publish). La version active n’est jamais modifiée.
Par exemple, pour insérer une branche après la vérification d’identité qui rejoint votre pipeline existant, vous n’avez qu’à envoyer : rediriger le next du nœud OCR vers une nouvelle branche, puis ajouter la branche, un nœud Declined final et une étape DOCUMENT_AI (dont le next renvoie à l’étape suivante d’origine). Les 10 autres nœuds, ainsi que leurs listes d’autorisation, restent inchangés.
« Après la vérification d’identité, si elle a été refusée, refuser ; si la profession ≈ « Software Engineer » (≥80%), demander un justificatif de fonds ; puis continuer. » → un seul nœud branch : kyc.status == Declined → un nœud de statut Declined ; kyc.extra_fields.profession fuzzy_match « Software Engineer » score 80 → un nœud DOCUMENT_AI de justificatif de fonds → et un chemin sinon qui revient dans le pipeline.
Une branche doit toujours avoir un chemin sinon explicite. La règle par défaut (le chemin emprunté lorsqu’aucune condition ne correspond) doit être une branche avec rules vide, par exemple { "id": "else", "rules": [], "goto": "<liveness>" }, et non le simple next du nœud de branche. Le MCP (et le backend) convertit automatiquement le next d’un nœud de branche en branche sinon, afin qu’une branche ne s’affiche jamais comme une arête ambiguë sans sinon visible.
Pour créer un nouveau workflow à partir de zéro, utilisez didit_workflow_validate_graph, puis didit_workflow_set_graph (graphe complet). Vous pouvez aussi laisser didit_workflow_build_graph assembler un graphe complet à partir d’une spécification de fonctionnalités simple, sans l’enregistrer. Même un simple didit_workflow_create est enregistré sous forme de ce même graphe de nœuds : le MCP assemble votre liste features en nœuds de fonctionnalité enchaînés, se terminant par un statut de décision automatique, afin que les fonctionnalités s’exécutent réellement (il publie par défaut ; passez status: "draft" pour le laisser non publié). Voir Créer un workflow → branches et workflows basés sur des nœuds pour la structure JSON complète.

​
Branches sur la raison d’omission du NFC avec le MCP

Pour un nouveau graphe, demandez :
« Créez un workflow brouillon avec la vérification d’identité suivie du NFC. Si nfc.skip_reason vaut DEVICE_WITHOUT_NFC ou DOCUMENT_WITHOUT_CHIP, envoyez la session en cours d’examen ; sinon, approuvez-la. Conservez une branche sinon explicite et validez le graphe avant de l’enregistrer. »
L’agent doit appeler didit_workflow_get_field_definitions, didit_workflow_validate_graph, puis didit_workflow_set_graph. Pour un workflow existant, demandez :
« Modifiez le workflow 26d33c04… : après son nœud NFC, redirigez chacune des sept valeurs connues de nfc.skip_reason vers « En cours d’examen », et conservez le chemin NFC réussi existant comme sinon explicite. Enregistrez un brouillon ; ne le publiez pas. »
L’agent doit appeler didit_workflow_search, didit_workflow_get_graph, didit_workflow_get_field_definitions, puis didit_workflow_edit_graph. L’outil de modification applique de petites opérations côté serveur : il conserve donc les nœuds sans rapport et les grandes listes d’autorisation. Voir Brancher selon la raison pour laquelle le NFC n’a pas été exécuté pour les sept valeurs, les règles equals et in, le comportement en cas de valeur nulle et un graphe complet ordonné.

​
Configurations des fonctionnalités et listes d’autorisation

Le config d’un nœud de fonctionnalité restreint ce qu’il accepte. didit_workflow_get_feature_config_schema renvoie chaque clé acceptée par chaque fonctionnalité, avec ses types et ses valeurs par défaut. Les deux outils de catalogue (didit_workflow_get_id_verification_methods_catalog et didit_workflow_get_kyb_registry_catalog) répondent aux questions pilotées par le serveur dont dépend une configuration. La liste d’autorisation OCR canonique suit l’ordre pays → document → objet : { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (par exemple { "ESP": { "P": { "enabled": 1 } } }). Le MCP normalise des formats plus simples avant la validation, de sorte que vous n’avez pas à écrire cette structure à la main : poa_languages_allowed de PROOF_OF_ADDRESS repose sur le même principe : transmettez un tableau de langues (["es"]) ou une table de correspondance ({ "es": 1 }). Ces simplifications s’appliquent partout où vous fournissez au MCP une configuration de fonctionnalité : les fonctionnalités de didit_workflow_create, ainsi que les config des nœuds dans set_graph, edit_graph et validate_graph.

​
Forme de la réponse (contrat V3)

Chaque outil renvoie le JSON brut de l’endpoint REST sous-jacent. Deux points à connaître :
  • Les outils synchrones (workflows, facturation, verify_* autonomes, gestion des listes) renvoient leur résultat final directement. Exploitez-le dans le même tour.
  • La création de session est asynchrone : didit_session_create renvoie une url que l’utilisateur doit compléter ; la décision arrive par webhook ou via didit_session_get_decision.
Les clés de décision sont toujours au pluriel et contiennent des tableaux, avec un node_id par entrée (id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], phone_verifications[], email_verifications[], database_validations[], reviews[], ainsi que, pour le KYB, registry_checks[], document_verifications[], key_people_checks[]). Voir Modèles de données et Statuts de vérification.

​
Gestion des webhooks

Faites en sorte qu’un webhook transmette la décision finale à votre backend, plutôt que d’interroger l’agent en continu :
  1. L’agent appelle didit_webhook_create une seule fois avec un label, votre url HTTPS publique, webhook_version: "v3" et subscribed_events (généralement ["status.updated", "data.updated"]). La réponse masque le secret de signature, de même que didit_webhook_get et didit_webhook_list. Copiez-le depuis Webhooks dans la console et stockez-le dans DIDIT_WEBHOOK_SECRET.
  2. Votre backend vérifie l’en-tête canonique X-Signature-V2 à chaque livraison : shortenFloats → sortKeys → JSON.stringify (unicode non échappé) → HMAC-SHA256 → timingSafeEqual. Rejetez la requête si abs(now − X-Timestamp) > 300 secondes.
  3. Dédupliquez sur event_id. Renvoyez un 2xx dans un délai de 5 secondes ; déportez les traitements lourds vers une file d’attente.
  4. Didit relance l’envoi en cas de 5xx ou 404, jusqu’à 2 fois (environ 1 min, puis environ 4 min), puis abandonne la livraison. Rejouez les envois échoués depuis l’onglet Livraisons de la console.
L’agent doit seulement configurer le récepteur ; il n’écoute pas lui-même. Contrat complet : Webhooks.

​
Transport et endpoints

L’endpoint est compatible avec deux générations de clients. Les clients qui fixent une version de protocole 2026-07-28 ou ultérieure dans chaque message ignorent la poignée de main initialize et peuvent appeler server/discover. Tous les clients antérieurs (Claude Code, Cursor, clients basés sur un SDK) utilisent la poignée de main Streamable HTTP standard, sans modification. Le CORS est ouvert : les clients basés sur le navigateur (le connecteur web de Claude, MCP Inspector) peuvent atteindre /mcp et les documents de découverte depuis une autre origine. La limite de taille du corps JSON est de 25 Mo, suffisante pour une entrée de fichier en base64 de 15 Mo.

​
Dépannage

Votre rôle dans cette organisation ne dispose pas de l’autorisation requise par l’outil (par exemple, un READER qui tente une écriture) ; l’erreur missing_scope la nomme. Si tous les outils échouent, reconnectez-vous ou relancez Log in with Didit. (Le MCP n’accepte que Bearer/OAuth : un x-api-key est rejeté par tous les outils, donc une clé API ne résoudra pas une erreur 403.)
Les outils destructifs exigent une confirmation dans votre client. Approuvez l’appel, ou vérifiez que l’invite de confirmation de l’outil n’est pas refusée automatiquement. didit_session_delete, didit_session_batch_delete et didit_org_reveal_application_api_key nécessitent en plus confirm: true dans les arguments de l’outil ; sans cela, l’appel est rejeté avant toute exécution.
Vous avez probablement plusieurs applications. Utilisez un outil *_search (qui couvre tout) ou exécutez didit_context_get et passez le organization_id / application_id souhaité.
Certains clients (Windsurf, Zed) se connectent via le pont mcp-remote : vérifiez que npx -y mcp-remote@latest https://mcp.didit.me/mcp figure dans la configuration. Rouvrez le client pour relancer la poignée de main OAuth.
Vérifiez que le serveur est connecté (la plupart des clients affichent un point d’état) et que vous avez terminé Log in with Didit. Redémarrez l’hôte MCP après avoir modifié sa configuration. didit_org_top_up et didit_org_reveal_application_api_key ne sont jamais listés sur le connecteur hébergé.
Assurez-vous de pointer vers https://mcp.didit.me/mcp, et non vers l’origine nue https://mcp.didit.me. Les métadonnées de ressource sont servies à /.well-known/oauth-protected-resource/mcp, limitées à ce chemin (avec une copie à la racine de l’origine pour les clients qui sondent cet emplacement). Si vous auto-hébergez, cela signifie généralement que MCP_RESOURCE_URI est défini sur l’origine au lieu de l’URL complète du transport ; voir Auto-hébergement.
Sur l’endpoint hébergé, envoyez le fichier au format *_base64 (base64 brut ou URL data:) ; *_path ne fonctionne que sur un serveur stdio local. Les fichiers sont limités à 15 Mo et doivent être des PNG, JPG, WebP, GIF, BMP, ICO ou PDF selon leur contenu, et pas seulement selon leur extension.

​
Sécurité

Le MCP agit avec vos autorisations réelles et peut modifier des ressources de production. Gardez « examiner les appels d’outils avant leur exécution » activé dans votre client, en particulier pour les outils d’écriture et destructifs. Le MCP lui-même ne stocke aucun secret dans votre configuration (il utilise Se connecter avec Didit), masque les clés API et les secrets de signature des webhooks dans la sortie des outils, exclut du catalogue hébergé les outils de recharge et outils liés aux clés brutes, et n’accepte jamais les identifiants de compte comme arguments d’outil sur un serveur distant. Chaque appel d’outil est inscrit dans le journal d’audit du serveur avec l’appelant, l’outil et le verdict d’autorisation.

​
Injection de prompt

Les outils Didit renvoient ce que vos utilisateurs ont saisi ou téléversé, comme des noms, le texte de documents et les réponses aux questionnaires. La personne vérifiée contrôle ce texte : elle peut donc écrire des instructions destinées à votre agent dans un nom ou un document, et le serveur renvoie ces champs tels qu’ils ont été saisis. Un agent ne peut pas distinguer de manière fiable ce texte de vos propres instructions. Traitez donc chaque résultat d’outil comme une donnée :
  • Gardez l’approbation des outils activée pour les outils d’écriture et destructifs, et lisez ce que l’agent s’apprête à faire avant de l’approuver.
  • Connectez-vous en tant que membre dont le rôle correspond à la tâche. Un agent qui ne fait que consulter des sessions peut utiliser un membre READER, et le backend refuse ses écritures quoi que tente l’agent.
  • Testez d’abord un nouvel agent ou un nouveau prompt sur une application sandbox.
  • N’approuvez ni ne refusez jamais une vérification parce qu’un texte présent dans cette vérification le demande. Fiez-vous à la décision, à ses avertissements et à votre propre examen.

​
Données personnelles

Les résultats d’outils peuvent contenir des données personnelles, comme des noms, des dates de naissance, des numéros de document et des liens vers des images, et votre client MCP les transmet au modèle qu’il utilise. Avant de connecter une application de production, vérifiez que votre contrat avec votre fournisseur d’IA couvre ces données, ou travaillez sur une application sandbox.

​
Auto-hébergement

Le serveur hébergé est construit à partir de github.com/didit-protocol/mcp (MIT). Clonez-le et lancez-le avec Docker ou Node ; il s’authentifie toujours en tant qu’utilisateur Didit (il n’existe pas de mode clé API), quel que soit le transport. Les étapes d’installation se trouvent dans Installation → auto-hébergement.

​
Variables d’environnement

.env.example dans le dépôt est un modèle à copier, et ARCHITECTURE.md explique la séparation entre serveur de ressources et serveur d’autorisation. Au démarrage, le serveur HTTP récupère le document de découverte du serveur d’autorisation et utilise les URL configurées si celui-ci est injoignable.

Référence des outils

Chaque outil, regroupé par domaine.

Exemples

Prompts et conversations de bout en bout.
Dernière modification le 7 novembre 2026