Brancher le serveur MCP

Le serveur MCP donne à un assistant conversationnel le droit d'interroger l'API publique de SealTrust, en lecture seule. MCP, pour Model Context Protocol, est le protocole normalisé par lequel un assistant appelle des outils extérieurs. Il existe sous deux formes, avec les mêmes sept outils : une adresse hébergée par SealTrust, https://mcp.sealtrust.io/mcp, à coller dans Claude ou ChatGPT, et un petit programme que vous lancez sur votre poste avec npx. En quittant cette page, vous saurez brancher l'une ou l'autre, choisir l'identifiant à passer et appeler les sept outils.

Le parcours tient en quatre étapes : vérifier que le périmètre correspond à votre besoin, brancher le serveur dans votre client, apprendre quel identifiant vous avez sous la main, appeler les outils.

Vous voulez qu'un assistant prépare le catalogue de votre marque, et pas seulement lire des passeports publiés ? C'est le rôle du serveur d'administration, décrit plus bas dans sa propre partie.

#1. Le périmètre, avant tout le reste

Le serveur n'émet que des requêtes GET, vers des points d'entrée publics de https://api.sealtrust.io. Il n'envoie aucune clef d'API et n'en accepte aucune. Aucun de ses outils ne crée, ne modifie ni ne supprime quoi que ce soit.

Conséquence directe : le serveur voit exactement ce que voit un visiteur anonyme qui ouvre un passeport dans son navigateur. Le règlement ESPR distingue plusieurs publics : le public, les consommateurs, les professionnels de la chaîne de valeur et les autorités de surveillance du marché. SealTrust applique cette distinction avec six niveaux d'accès : public, end_user, repairer, recycler, upstream et authority. Ces valeurs sont celles de SealTrust. Le règlement, lui, nomme des publics. Le serveur MCP lit le niveau public et uniquement lui. Les champs réservés aux professionnels ou aux autorités ne sont pas atteignables par ce chemin.

Ce que le serveur annonce à votre client au moment de la connexion : son nom, sealtrust, sa version, et une phrase d'instructions qui rappelle à l'assistant que toutes les données sont publiques et qu'aucun outil ne modifie rien.

#2. Brancher le serveur

#Sans rien installer : l'adresse hébergée

L'adresse https://mcp.sealtrust.io/mcp sert les mêmes sept outils, avec les mêmes descriptions, que le programme décrit plus bas. Elle ne demande ni compte ni clef. Dans Claude, ajoutez-la comme connecteur personnalisé. Dans ChatGPT, activez le mode développeur puis créez un connecteur avec cette adresse. Les étapes exactes, écran par écran, sont dans Claude et ChatGPT en 30 secondes.

Avec Claude Code, sans Node.js :

claude mcp add --transport http sealtrust https://mcp.sealtrust.io/mcp

Le transport est le HTTP diffusable (« Streamable HTTP ») de la spécification MCP, sans session : chaque message est une requête POST indépendante. Un GET ou un DELETE sur l'adresse répond 405. Les plafonds de cette adresse sont au point 6.

#Sur votre poste : le paquet npm

Il vous faut Node.js en version 18 ou plus récente. Le paquet s'appelle @sealtrust-io/mcp-server et la dernière version publiée est 0.4.0.

Vous pouvez le lancer directement, ce qui sert à vérifier qu'il démarre.

npx @sealtrust-io/mcp-server

Le serveur communique par son entrée et sa sortie standard. Une ligne de démarrage part sur la sortie d'erreur et indique la version ainsi que l'adresse d'API utilisée. La sortie standard est réservée au dialogue avec le client, donc rien d'autre n'y est écrit.

#Déclarer le serveur dans un client

Un client MCP se configure avec une commande et ses arguments. Le bloc ci-dessous est la forme attendue par les clients de bureau, à placer dans leur fichier de configuration.

{
  "mcpServers": {
    "sealtrust": {
      "command": "npx",
      "args": ["-y", "@sealtrust-io/mcp-server"]
    }
  }
}

En ligne de commande avec Claude Code, la même déclaration s'écrit ainsi.

claude mcp add sealtrust -- npx -y @sealtrust-io/mcp-server

Redémarrez le client après avoir modifié sa configuration. Les sept outils apparaissent alors dans sa liste d'outils disponibles.

#Les réglages disponibles

Trois variables d'environnement changent le comportement du programme lancé avec npx. En pratique, seules les deux premières vous servent.

Le délai couvre l'aller-retour complet, en-têtes et corps de réponse compris. Un dépassement rend une erreur de réseau explicite, jamais un blocage silencieux.

Ces deux variables se posent dans la configuration de votre client, sous la clef env. Le bloc ci-dessous est complet et copiable tel quel. Il porte un délai de 30 secondes.

{
  "mcpServers": {
    "sealtrust": {
      "command": "npx",
      "args": ["-y", "@sealtrust-io/mcp-server"],
      "env": {
        "SEALTRUST_TIMEOUT_MS": "30000"
      }
    }
  }
}

#3. Savoir quel identifiant vous avez

Six outils sur sept prennent un identifiant de produit. Quatre formes existent, et elles ne sont pas acceptées partout.

L'alphabet du numéro de série exclut les lettres I, L, O et U, pour qu'une personne qui recopie une étiquette ne confonde pas une lettre avec un chiffre. Le serveur MCP transmet le numéro tel qu'on le lui donne, sans réécrire aucun caractère. C'est l'API qui remet le numéro en majuscules et qui ramène les caractères ambigus à leur forme canonique : I et L valent 1, O vaut 0.

Deux outils prennent en plus un GTIN, le code article à 8, 12, 13 ou 14 chiffres. Un GTIN désigne un modèle. Il ne désigne aucun exemplaire en particulier.

#4. Les sept outils

#verify_product

Répond à la question « ce numéro est-il enregistré, et son certificat est-il en vigueur ». Il ne dit jamais que l'objet en main est l'original : un QR code ou un numéro de série se copie, seule la lecture d'une puce le prouve. L'outil enchaîne deux appels : la résolution de l'identifiant, puis la lecture du certificat.

La réponse porte un champ status qui prend cinq valeurs.

Viennent avec : un champ message en clair, un bloc product qui porte le nom du produit, le nom de la marque, la catégorie, l'identifiant de jeton, l'empreinte d'identifiant, l'adresse du contrat, l'opération de frappe et la date de création, un bloc certificate ou la valeur nulle, un booléen has_published_passport, et un booléen anchored_on_base.

anchored_on_base vaut vrai quand un ancrage existe, quel qu'il soit : celui du lot de produits, ou celui du contenu du passeport. Les deux sont indépendants. Un passeport peut être ancré alors que son lot ne l'a pas été, et l'inverse. Pour savoir lequel des deux, et avec quelle opération, appelez get_passport_proof.

Attendez-vous à ce que ce booléen vaille faux la plupart du temps. L'ancrage est une opération que SealTrust déclenche à la main. Une demande d'ancrage venue d'un compte de marque est refusée. Frapper un produit ne l'ancre pas, et publier un passeport ne l'ancre pas non plus. La plupart des produits ne sont jamais ancrés. Un anchored_on_base à faux ne dit donc rien contre le produit, et votre assistant ne doit jamais le présenter comme un soupçon.

#get_passport

Rend le passeport numérique publié, au niveau d'accès public.

La réponse au format par défaut porte la version du passeport, le contenu publié sous le champ data, l'empreinte SHA-256 de ce contenu sous data_hash, le nom du produit et de la marque, le GTIN et le lien GS1 Digital Link du produit.

Les deux champs qui pointent vers la copie IPFS valent toujours la valeur nulle sur ce chemin. Ils sont réservés aux niveaux d'accès authentifiés. Le lien vers la copie immuable, quand elle est publiée, apparaît dans la réponse de get_passport_proof.

#get_passport_proof

Rend les preuves publiques qui permettent de vérifier un passeport sans nous faire confiance.

Vous devez fournir exactement l'un des deux. Aucun des deux, ou les deux à la fois, donne un refus immédiat avec un message qui explique la différence. Les deux paramètres ne désignent pas la même chose : la preuve d'un exemplaire date l'objet, la preuve d'une référence date le document.

La réponse contient l'empreinte du contenu, le lien vers la copie IPFS quand elle est publiée, un bloc seal qui dit si la version est scellée et si son contenu correspond encore à ce qui a été scellé, l'état d'émission de l'attestation vérifiable, et le nombre de vérifications physiques réussies. Une preuve absente est absente de la réponse, sans champ vide.

Un passeport de niveau référence, celui qu'on obtient avec gtin, ne porte légitimement ni bloc anchor ni compte de vérifications. Il n'est lié à aucun exemplaire physique. Sa preuve est l'ancrage de son propre contenu, qui date le document. La réponse porte alors level: "model" et le GTIN normalisé.

#get_product_history

Rend l'historique d'un produit : les mouvements de propriété et les scans d'authentification, réunis dans une seule chronologie, du plus récent au plus ancien. Le premier élément de timeline est l'événement le plus récent.

Chaque entrée porte un champ type qui vaut verify pour un scan ou transfer pour un mouvement de propriété, un horodatage, l'identifiant de jeton et l'empreinte d'identifiant. Le reste dépend du type. Une entrée verify porte un indicateur de validité et aucun libellé de partie. Une entrée transfer porte deux libellés prêts à l'affichage, pour la partie qui cède et celle qui reçoit, et aucun indicateur de validité.

Pour un appelant anonyme, et le serveur MCP en est un, les identités sont masquées : les adresses électroniques sont anonymisées et les adresses de portefeuille brutes ne sont pas rendues.

#get_certificate

Rend le certificat d'authenticité public d'un produit.

La réponse porte le numéro du certificat, son état, sa date d'émission, sa date de fin quand elle existe, le nom de l'émetteur, le nom du produit et celui de la marque, ainsi que les champs personnalisés enregistrés à l'émission, rendus tels quels. Tout ce qui y est écrit est public.

#resolve_gs1

Part d'un lien GS1 Digital Link et rend le passeport qu'il désigne.

La présence du numéro de série change ce que le lien désigne. Avec lui, le lien /01/{gtin}/21/{serial} désigne un exemplaire précis et la réponse porte level: "item". Sans lui, le lien /01/{gtin} désigne la classe d'articles et rend le passeport de niveau référence, celui que partagent tous les exemplaires du modèle, avec level: "model". C'est ce second niveau que servent les codes de modèle déjà imprimés. Une chaîne vide dans serial est lue comme une absence.

La réponse porte aussi le lien reconstruit, l'adresse vers laquelle la résolution redirige, l'identifiant retenu, et le passeport public quand il en existe un.

Sans passeport de référence publié, /01/{gtin} répond 404 et l'outil rend found: false avec le message « Unknown GS1 Digital Link ». Le résultat resolved: true accompagné d'un passeport nul ne survient que lorsque vous fournissez un serial et que cet exemplaire n'a pas de passeport publié.

Le numéro de série attendu ici est bien celui qui est imprimé sur le produit. L'identifiant de jeton en chaîne ne convient pas à cet endroit.

#verify_credential

Vérifie la signature de l'attestation vérifiable du passeport, au format SD-JWT-VC, contre la clef publiée par la marque émettrice sous la forme did:web.

Passez identifier ou gtin, jamais les deux. Le passeport d'un modèle ou d'un lot n'est rattaché à aucun exemplaire, et une marque à l'offre Conformité n'en enregistre aucun : gtin est alors la seule façon d'atteindre son attestation. Ces deux paramètres arrivent avec la version 0.6.0 du serveur, pas encore publiée : la version 0.4.0 publiée ne prend que identifier.

La réponse porte verified, l'identifiant décentralisé de l'émetteur, le type de l'attestation, la version de la clef de signature, le niveau d'accès appliqué, un champ error valant verification_failed en cas d'échec, et le contenu de l'attestation quand la signature est valide.

#5. Lire les réponses et les erreurs

Le serveur sépare trois situations, et cette séparation compte pour un assistant qui raisonne sur le résultat.

Un argument mal formé est refusé avant tout appel réseau : un identifiant vide, un format qui n'est ni json ni jsonld, ou l'absence de choix entre identifier et gtin sur la preuve.

#6. Les plafonds d'appels

#Sur l'adresse hébergée

L'adresse https://mcp.sealtrust.io/mcp applique trois plafonds, tous sur une fenêtre de 60 secondes.

Le troisième plafond existe parce que le serveur hébergé joint l'API depuis une seule adresse, la sienne. L'API compte par adresse : tous les utilisateurs de l'adresse hébergée partagent donc ses plafonds du tableau suivant, et le serveur en garde 80 % pour ne jamais se les voir refuser. Au-delà, l'outil rend une erreur qui commence par SealTrust API error (429) et dit dans combien de secondes réessayer, sans avoir appelé l'API.

Claude et ChatGPT appellent depuis les serveurs de leur éditeur. Beaucoup d'utilisateurs partagent donc quelques adresses, et un 429 peut venir d'un autre utilisateur que vous. Si vous en rencontrez souvent, lancez le paquet npm sur votre poste : il appelle l'API depuis votre propre adresse.

#Sur l'API, pour le paquet npm

Les points d'entrée publics sont plafonnés par adresse IP appelante, sur une fenêtre de 60 secondes. Les familles de chemins qui ont un plafond à elles tiennent chacune leur propre compteur. Les autres relèvent d'un compteur général, commun à toutes les routes sans plafond dédié.

Deux outils consomment deux appels au lieu d'un. verify_product interroge la résolution puis le certificat. resolve_gs1 lit la redirection du résolveur sans la suivre, puis demande le passeport directement. Comptez-les comme deux.

Un dépassement rend une réponse 429, que le serveur remonte en erreur d'outil. Un cas fait exception. Sur verify_product, seul le premier appel remonte un 429. Un dépassement sur la lecture du certificat est journalisé sur la sortie d'erreur et l'outil répond quand même, avec le certificat résumé que porte déjà la résolution.

#Le serveur d'administration : l'assistant prépare, une personne publie

Un second serveur, @sealtrust-io/mcp-admin, sert une seule marque. Avec lui, un assistant prépare votre catalogue : il crée des modèles et des lots, ouvre des brouillons de passeport, les complète, et vous montre ce qui manque encore. Il ne publie jamais. Publier scelle une version pour toujours, donc une personne relit le brouillon et le publie dans la console.

Il existe sous deux formes, avec les mêmes outils et les mêmes refus : une adresse hébergée, https://mcp.sealtrust.io/admin/mcp, que vous ajoutez comme connecteur dans Claude et où vous vous connectez avec votre compte de la console ; et un programme lancé sur votre poste avec la clé de votre marque. L'adresse https://mcp.sealtrust.io/mcp, elle, reste celle du serveur public, en lecture seule.

#Ce qu'il fait, et ce qu'il refuse

Il refuse, avec un message qui renvoie à la console : publier un passeport, ancrer ou frapper sur la chaîne, transférer, émettre des codes d'achat, supprimer quoi que ce soit, gérer les clés, l'équipe, la facturation ou les règles d'accès. update_passport_draft refuse aussi une version scellée : une correction commence par un nouveau brouillon. Les brouillons de passeport d'exemplaire se préparent dans la console.

#L'adresse hébergée : l'ajouter dans Claude

Rien à installer, et aucune clé à copier : vous vous connectez avec votre compte de la console, et vous choisissez ce que l'assistant a le droit de faire.

1. Dans Claude, ouvrez Paramètres, puis Connecteurs, puis « Ajouter un connecteur personnalisé ». Donnez-lui un nom, par exemple SealTrust admin, et l'adresse https://mcp.sealtrust.io/admin/mcp.
2. Cliquez sur « Se connecter ». Claude ouvre la console SealTrust. Connectez-vous avec votre compte, double authentification comprise si elle est activée.
3. La page « Connecter un assistant IA » vous montre qui demande l'accès et l'adresse où vous serez renvoyé, qui doit être celle de Claude. Choisissez UNE marque parmi celles que vous administrez. « Lire le catalogue » est toujours accordé. « Préparer des brouillons » n'est jamais coché d'avance : cochez-le vous-même si l'assistant doit aussi créer et compléter.
4. Cliquez sur « Autoriser ». Claude reprend la main et les outils apparaissent. Sans « Préparer des brouillons », les cinq outils d'écriture n'apparaissent pas, et l'API les refuserait de toute façon.

Pour Claude Code, la même adresse s'ajoute ainsi, et la connexion se fait dans votre navigateur.

claude mcp add --transport http sealtrust-admin https://mcp.sealtrust.io/admin/mcp

#Mettre fin à une connexion

Dans la console, ouvrez Paramètres, puis Développeurs : la carte « Assistants IA connectés » liste les connexions de vos marques, les vôtres et celles de vos collègues, avec la marque, la personne qui l'a autorisée, la date de dernière utilisation et la date de fin. « Mettre fin à cette connexion » coupe l'accès dès la requête suivante de l'assistant.

Une connexion prend fin aussi d'elle-même quand la personne qui l'a autorisée perd ses droits sur la marque ou n'a plus de compte actif. Retirer le connecteur dans Claude ne suffit pas toujours à révoquer l'accès : mettez fin à la connexion dans la console.

#Sur votre poste : la clé, une par marque

Le serveur appelle l'API partenaire avec une clé d'API de votre marque. Créez-la dans la console, Paramètres puis Développeurs, avec les droits catalog:read et catalog:write. Créez une clé réservée à cet usage : vous pourrez la révoquer sans couper vos autres intégrations.

La clé passe dans l'environnement du serveur, jamais dans la conversation. Aucun outil ne prend de marque ni de clé en argument. Au premier appel, le serveur demande à l'API pour quelle marque la clé agit. Il refuse de travailler si elle agit pour plusieurs marques : une clé de revendeur ne convient pas, créez une clé par marque cliente.

#Le brancher

Le paquet vous est remis par SealTrust : il n'est pas publié sur npm. Indiquez à votre client le chemin du fichier dist/index.js du paquet.

{
  "mcpServers": {
    "sealtrust-admin": {
      "command": "node",
      "args": ["/chemin/vers/mcp-admin/dist/index.js"],
      "env": {
        "SEALTRUST_ADMIN_API_KEY": "st_live_votre_cle",
        "SEALTRUST_BRAND_CODE": "7K3QXW9M2A"
      }
    }
  }
}

Avec Claude Code, la même déclaration s'écrit ainsi.

claude mcp add sealtrust-admin \
  -e SEALTRUST_ADMIN_API_KEY=st_live_votre_cle \
  -e SEALTRUST_BRAND_CODE=7K3QXW9M2A \
  -- node /chemin/vers/mcp-admin/dist/index.js

#Le parcours type

1. Demandez à l'assistant de partir d'un gabarit : list_dpp_templates, puis create_passport_draft avec template.
2. Donnez-lui vos informations. Il complète le brouillon avec update_passport_draft. Il ne doit inventer ni un chiffre ni une déclaration réglementaire : ce que vous ne lui donnez pas reste vide.
3. Il lit get_readiness pour vous dire ce qui manque, puis preview_passport pour vous montrer ce que chaque public verra.
4. Vous relisez et vous publiez dans la console, page Passeports.

#Ce qui vous protège

• Chaque appel passe par l'API, avec votre clé. Le journal d'activité de la marque enregistre chaque écriture au nom de la clé, et les plafonds de l'API s'appliquent.
• Le serveur n'appelle que les points d'entrée du catalogue de votre marque. Toute autre adresse est refusée avant l'envoi.
• Tout ce que l'API renvoie est présenté à l'assistant comme une donnée non fiable. Un texte écrit dans un passeport ne déclenche aucun outil, même s'il ressemble à un ordre.
• La clé n'apparaît ni dans les journaux du serveur, ni dans ses réponses.
• Sur l'adresse hébergée, chaque autorisation, chaque usage d'un jeton et chaque fin de connexion est inscrit au journal d'activité, au nom de la personne qui a autorisé la connexion. SealTrust ne conserve que l'empreinte des jetons, jamais les jetons eux-mêmes.
• Un jeton n'est valable que pour le serveur d'administration de SealTrust, et pour une seule marque. Présenté directement à l'API, il est refusé.

#Ce qui peut vous arrêter