Hébergement autonome du serveur MCP Didit : Guide complet (FR)

Points clés à retenir

• Le serveur Didit Model Context Protocol (MCP) est open source sous licence MIT. Vous pouvez le construire à partir du dépôt public GitHub et l'exécuter avec Docker, Node.js, ou un transport stdio sans interface graphique.
• L'auto-hébergement modifie l'endroit où le processus MCP s'exécute, pas la manière dont il atteint Didit. Chaque mode s'authentifie en tant qu'utilisateur Didit avec un jeton d'accès Bearer. Il n'existe pas de mode clé API d'application pour les outils MCP.
• Le catalogue complet auto-hébergé contient 121 outils. Le point de terminaison OAuth (Open Authorization) hébergé en expose intentionnellement 115. Les exemples dans la source actuelle incluent didit_context_get, didit_session_create et didit_transaction_screen_wallet.
• Le point d'entrée HTTP est "stateless" et accepte le trafic MCP via des requêtes POST. Un nouveau serveur et un nouveau transport sont créés par requête, de sorte qu'un équilibreur de charge n'a pas besoin d'affinité de session.
• Utilisez /healthz pour les vérifications de conteneur et d'équilibreur de charge. Configurez l'URI de ressource publique, l'origine d'autorisation, le mode de vérification des jetons et les secrets explicitement avant d'exposer le service.

Le point de terminaison hébergé est pratique, mais ce n'est pas le bon choix opérationnel pour toutes les équipes. Une entreprise peut avoir besoin de garder l'intégration à l'intérieur de sa propre limite de réseau, de contrôler l'image d'exécution, de router le trafic via une couche d'égression privée, ou d'appliquer ses propres politiques d'observabilité et de gestion des changements. Le dépôt Didit MCP prend en charge ce modèle de déploiement sans créer une surface produit distincte.

Ce guide se concentre uniquement sur l'exploitation du serveur. Pour le catalogue et le comportement des outils, utilisez la référence des outils Didit MCP. Pour la configuration du client par rapport au point de terminaison géré, utilisez le guide d'installation de Claude. Les références techniques complètes se trouvent dans l'aperçu MCP et la documentation d'authentification.

Choisissez le point d'entrée HTTP ou stdio

Le dépôt construit un catalogue d'outils partagé avec deux points d'entrée. dist/http.js exécute un serveur de ressources Express sur HTTP "Streamable" sans état. C'est le bon choix pour un service partagé accessible par plusieurs clients MCP, conteneurs ou utilisateurs. dist/index.js s'exécute sur stdio et est destiné à un processus local sans interface graphique lancé par un seul client.

Les deux points d'entrée appellent la même logique de répartition, et la version 5 expose uniquement les outils MCP – pas les ressources ou les invites MCP. Les deux authentifient les requêtes en aval en tant qu'utilisateur Didit. La différence réside dans la manière dont cette information d'identification d'utilisateur atteint le processus : le point d'entrée HTTP reçoit et valide le jeton Bearer OAuth de l'appelant ; le point d'entrée stdio lit un jeton Bearer d'utilisateur à partir de DIDIT_ACCESS_TOKEN.

L'auto-hébergement ne signifie pas sans identifiants : le MCP agit toujours en tant qu'utilisateur Didit, et Didit applique le rôle et les permissions de l'organisation de cet utilisateur à chaque appel d'outil.

Construire et exécuter avec Docker

Le dépôt inclut un Dockerfile multi-étapes basé sur Node 20. L'étape de construction installe les dépendances de développement, compile TypeScript et élague les packages de développement. L'étape de production s'exécute en tant qu'utilisateur node non-root et inclut une vérification de l'état du conteneur.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

Avant de démarrer le conteneur, remplacez les valeurs par défaut hébergées qui identifient votre déploiement. Au minimum, définissez MCP_RESOURCE_URI sur l'origine publique par laquelle les clients atteignent ce serveur de ressources, puis fournissez les identifiants client OAuth nécessaires à l'introspection du jeton. Gardez les secrets dans le gestionnaire de secrets de votre plateforme de conteneurs plutôt que de valider le fichier .env rempli.

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Terminez la sécurité de la couche de transport (TLS) au niveau de votre entrée ou de votre équilibreur de charge, transférez les requêtes POST MCP au port 3000 et préservez l'en-tête Authorization. L'MCP_RESOURCE_URI visible de l'extérieur doit correspondre à l'identité de la ressource annoncée aux clients ; ne laissez pas l'URI Didit gérée en place pour une origine publique différente.

Construire et exécuter directement avec Node.js

Si votre plateforme gère déjà un environnement d'exécution Node, utilisez le même point d'entrée HTTP sans conteneur. Le package est privé et n'est pas distribué via npm, alors clonez le dépôt plutôt que d'essayer d'exécuter un package publié.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

Le processus lit les mêmes variables d'environnement que le conteneur. Exécutez-le sous votre superviseur de processus, injectez les secrets via l'environnement de déploiement et ne routez que les points de terminaison requis. Les requêtes MCP vont à POST /mcp. Le service rejette délibérément GET et DELETE sur cette route car il ne maintient pas de sessions MCP ni de flux initiés par le serveur.

Node.js ne charge pas automatiquement le fichier .env du dépôt. Exportez les valeurs dans le shell, injectez-les via le gestionnaire de services, ou utilisez la prise en charge des fichiers d'environnement de votre plateforme avant de démarrer dist/http.js. Notez également que npm start lance le point d'entrée stdio ; utilisez node dist/http.js ou npm run start:http pour HTTP.

Exécuter sans interface graphique via stdio

Pour un agent local, un exécuteur de build ou un processus isolé à client unique, utilisez le point d'entrée stdio. Fournissez un jeton d'accès utilisateur via l'environnement et laissez le client MCP gérer le cycle de vie du processus.

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

Ce jeton est une information d'identification Bearer utilisateur, pas une information d'identification d'application. Stockez-le en tant que secret, gardez-le hors de l'historique du shell et des journaux, et faites-le pivoter selon votre politique d'accès. Si un déploiement opère toujours dans une seule organisation ou application, MCP_DEFAULT_ORG et MCP_DEFAULT_APP peuvent fournir cette portée par défaut. Sinon, les outils peuvent résoudre la portée à partir d'arguments explicites ou du contexte de la requête authentifiée.

Il n'y a toujours pas de mode clé API d'application dans stdio. Le HTTP auto-hébergé et le stdio auto-hébergé appellent tous deux les points de terminaison de la console Didit à portée utilisateur, de sorte qu'une clé d'application ne peut pas remplacer le jeton Bearer utilisateur.

Configurer la surface d'environnement complète

Le fichier src/config.ts actuel prend en charge les variables suivantes. La plupart des déploiements devraient conserver les valeurs par défaut de l'API Didit de production et d'autorisation et ne remplacer que l'identité de la ressource, la configuration de vérification et les secrets nécessaires à leur topologie.

Variables partagées et stdio

• DIDIT_ACCESS_TOKEN : jeton Bearer utilisateur pour le mode stdio sans interface graphique ; pas de valeur par défaut.
• DIDIT_API_BASE_URL : base de l'API de vérification ; par défaut à https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL : base de l'API d'authentification ; par défaut à https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG et MCP_DEFAULT_APP : valeurs par défaut facultatives d'organisation et d'application pour les déploiements à locataire unique.

Variables du serveur de ressources HTTP

• MCP_PORT : port d'écoute ; par défaut à 3000.
• MCP_RESOURCE_URI : URI du serveur de ressources public ; par défaut à https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN : origine du serveur d'autorisation ; par défaut à https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE : introspection par défaut, ou jwks lorsque le service d'autorisation émet des jetons Web JSON (JWT) adaptés à la vérification de signature locale.
• MCP_OAUTH_CLIENT_ID et MCP_OAUTH_CLIENT_SECRET : pas de valeurs par défaut ; utilisés comme identifiants HTTP Basic pour l'introspection RFC 7662.
• MCP_OAUTH_INTROSPECT_URL : par défaut à https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED : étendues de découverte séparées par des espaces ; par défaut à didit:management didit:verification.

Remplacements des métadonnées d'autorisation

• DIDIT_AUTH_ISSUER : par défaut à MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL : document de découverte OpenID Connect (OIDC) ; par défaut à l'origine d'autorisation plus /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL : point de terminaison JSON Web Key Set (JWKS) ; par défaut à https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL : par défaut à l'origine d'autorisation plus /authorize.
• DIDIT_OIDC_TOKEN_URL : par défaut à l'origine d'autorisation plus /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL : par défaut à l'origine d'autorisation plus /api/auth/oauth-register.

Utilisez l'introspection pour les jetons d'accès opaques. Le serveur les envoie au point de terminaison d'introspection configuré en utilisant MCP_OAUTH_CLIENT_ID et MCP_OAUTH_CLIENT_SECRET. N'utilisez jwks que lorsque votre service d'autorisation est configuré pour émettre des jetons d'accès JWT signés pour ce client ; le serveur valide ensuite les signatures par rapport à DIDIT_JWKS_URL. Changer le mode de vérification ne crée pas un modèle d'identité différent : le principal validé reste un utilisateur Didit.

Les clients MCP peuvent utiliser l'enregistrement client dynamique (DCR) avec la console Didit Business pendant leur flux d'autorisation. Cet enregistrement client est distinct des MCP_OAUTH_CLIENT_ID et MCP_OAUTH_CLIENT_SECRET du serveur de ressources, qui authentifient les requêtes d'introspection. Fournissez ces identifiants côté serveur via le canal de déploiement Didit approprié plutôt que de supposer qu'un enregistrement client peut les remplacer.

Contrôles de santé et mise à l'échelle "stateless"

Le processus HTTP expose GET /healthz et renvoie du JSON contenant status, service et version. L'image Docker le vérifie déjà toutes les 30 secondes après une période de démarrage de 15 secondes. Vous pouvez utiliser le même point de terminaison pour la préparation de Kubernetes, un groupe cible d'équilibreur de charge d'application ou une sonde de temps de fonctionnement externe.

curl -fsS http://localhost:3000/healthz

La route MCP est "stateless" par conception. Pour chaque POST authentifié, le processus crée un nouveau serveur et un nouveau transport HTTP "Streamable" avec la génération de session désactivée, transmet l'identifiant validé de l'appelant via le contexte par requête, termine la répartition et ferme le transport. Il n'y a pas de session en mémoire qu'une requête ultérieure doit trouver sur la même réplique.

Ici, "stateless" décrit le transport MCP et le cycle de vie des requêtes. Les sessions de vérification, les flux de travail, les cas et autres enregistrements commerciaux persistent toujours dans les services en amont de Didit.

En conséquence, les répliques horizontales n'ont pas besoin de sessions persistantes. Toute instance saine peut gérer le POST suivant, et les déploiements progressifs ne nécessitent pas de vidage de session au-delà de la gestion ordinaire des requêtes en cours. La planification de la capacité doit se concentrer sur la concurrence des requêtes, la latence de l'API Didit en aval et votre politique normale de délai d'attente et de nouvelle tentative.

Valider avant d'exposer le service

• Confirmez que /healthz réussit à partir du même chemin réseau que l'équilibreur de charge.
• Confirmez que les requêtes MCP non authentifiées reçoivent un défi d'autorisation plutôt qu'une sortie d'outil.
• Complétez un flux OAuth 2.1 avec Proof Key for Code Exchange (PKCE), puis appelez didit_context_get pour vérifier que les organisations et applications attendues sont visibles.
• Consultez la documentation MCP avancée avant de modifier les points de terminaison de découverte ou la vérification des jetons.
• Utilisez la page développeur Didit MCP pour la surface gérée prise en charge et les liens actuels.

Si l'auto-hébergement n'est plus une exigence, le point de terminaison géré supprime les opérations d'exécution et de serveur de ressources OAuth décrites ci-dessus. Les utilisateurs de Claude peuvent l'ajouter avec le lien profond du connecteur Didit. Que vous exécutiez le processus ou que Didit le fasse, la règle de base est identique : les opérations MCP s'authentifient en tant qu'utilisateur Didit, jamais en tant que clé API d'application.