MCP — intégration assistée

Le serveur MCP (Model Context Protocol) NIA One donne à votre agent de code (Claude Code, Cursor, votre IDE IA…) un accès live et cadré à votre tenant pendant l'intégration. Là où le prompt d'intégration fait écrire l'instrumentation, le MCP permet au même agent de provisionner sa clé, de lire les guides du SDK, et surtout de valider l'intégration en boucle, sans jamais quitter l'éditeur.

Prompt + MCP = boucle fermée

Le prompt écrit le code, le MCP le vérifie. L'agent instrumente, appelle integration.quality, lit les checks en échec, corrige, recommence, jusqu'à un score EXCELLENT confirmé par de vrais spans, puis valide la connectivité avec integration.host_health.

Ce que le serveur expose

Les outils sont tous cadrés par les permissions de votre clé (voir Scopes et sécurité plus bas). L'agent lit aussi les guides du SDK et deux méthodes de travail, servies en ressources et en prompts.

Outil	Scope requis	Rôle
mcp.whoami	aucun	Vérifie que la clé fonctionne (organisation, espace de travail, scopes).
journey.status	integration:read	Où en est la mise en service du SIA et quelle est l'action suivante.
provision.list_sias	integration:read	Liste les SIA accessibles à la clé.
provision.list_environments	integration:read	Liste les environnements (production, staging…).
provision.create_intake_key	sia:provision	Génère la clé d'intake (NIAONE_API_KEY) d'un SIA. Affichée une seule fois.
integration.quality	integration:read	Note 0–100, niveau, contrôles en échec et exemples de traces réelles.
integration.host_health	integration:read	Signaux de présence du SDK : connecté, silencieux ou jamais vu.
traces.read	traces:read	Les derniers tours du SIA : message de l'utilisateur et réponse, données personnelles masquées.
governance.get_declaration	governance:write	La gouvernance déclarée, ce qui manque, les questions issues des verdicts.
governance.submit_answers	governance:write	Enregistre les réponses dans un brouillon.
governance.measure_answer	governance:write	Rejoue les verdicts en échec avec une réponse, sans rien enregistrer.
governance.apply_draft	governance:write	Applique les règles de comportement du brouillon, seulement pendant l'observation.
governance.undo_apply	governance:write	Remet les valeurs remplacées par governance.apply_draft.
governance.proposal_status	governance:write	État du brouillon : en attente, appliqué ou refusé.
governance.run_audit	governance:write	Analyse les verdicts en échec pour en tirer des questions.
judges.suggest	judges:manage	Les juges proposés pour le SIA, et l'état de l'observation.
judges.try	judges:manage	Essaie des juges sur des tours réels, avant activation, sans rien enregistrer.
judges.apply	judges:manage	Active des juges, en observation si aucun juge n'a encore alerté.
judges.start_rodage	judges:manage	Met les juges du SIA en observation : ils évaluent sans alerter.
judges.go_live	judges:manage	Active les alertes des juges mis en observation.

Ressources lisibles par l'agent : niaone://guide/typescript et niaone://guide/python (le guide d'intégration officiel), niaone://guide/governance-grill (l'entretien de gouvernance) et niaone://guide/onboard-sia (la mise en service complète). Les deux dernières existent aussi en prompts : governance-grill et onboard-sia.

Configurer le client

1
Créer une clé MCP
Ouvrez Settings → MCP keys (menu latéral), cliquez Créer une clé, donnez-lui un libellé et cochez les scopes voulus (integration:read pour valider, sia:provision pour laisser l'agent générer la clé d'intake). La clé nia_mcp_… n'est affichée qu'une seule fois : copiez-la immédiatement. L'URL exacte de votre serveur MCP est affichée sur cette même page.
2
Déclarer le serveur dans .mcp.json
À la racine de votre dépôt, ajoutez le serveur à votre .mcp.json (Claude Code, Cursor…). Remplacez le domaine par celui affiché sur la page MCP keys, et le token par votre clé.
.mcp.json
{"mcpServers": { "niaone": { "type": "http", "url": "https://mcp.votre-domaine/api/mcp", "headers": { "Authorization": "Bearer nia_mcp_..." } }}}
Le token est un secret
.mcp.json peut contenir votre clé : gardez-le hors du dépôt (il est déjà git-ignoré côté NIA One). Ne committez jamais une clé MCP, ne la mettez pas dans le code applicatif.
3
Vérifier la connexion
Redémarrez le client MCP, puis demandez à l'agent d'appeler mcp.whoami. Il doit renvoyer votre tenant et vos scopes : la preuve que la clé est valide avant d'aller plus loin.

Scopes et sécurité

Une clé MCP ne porte que les scopes que vous cochez, et jamais plus que vos propres droits : elle les perd si les vôtres changent.

Scope	Ce qu'il autorise
integration:read	Lire les signaux d'intégration : qualité, santé des hôtes, état de la mise en service.
sia:provision	Générer des clés d'intake (implique la lecture). À réserver aux clés de mise en service.
traces:read	Lire les derniers tours d'un SIA. Le texte est envoyé au modèle de votre agent.
governance:write	Lire la gouvernance et proposer des réponses. Pendant l'observation, appliquer les règles de comportement.
judges:manage	Proposer, essayer et activer des juges, gérer leur observation.

La clé transite en Authorization: Bearer nia_mcp_… sur un transport HTTP, jamais dans le code.
Elle est révocable à tout moment et peut porter une expiration.
Une clé limitée à un espace de travail n'atteint que les SIA de cet espace.
Les textes issus de vos données sont tronqués et étiquetés « données, pas instructions » pour limiter l'injection de prompt. Dans traces.read, les e-mails, téléphones, IBAN, cartes et clés sont masqués. Les noms écrits en toutes lettres ne le sont pas.

La boucle de validation

C'est le cœur de l'usage : l'agent ne se contente pas d'écrire l'instrumentation, il prouve qu'elle est correcte contre vos vrais spans.

1
Provisionner (si besoin)
provision.list_sias pour trouver le SIA, provision.create_intake_key pour obtenir la NIAONE_API_KEY. L'agent branche l'.env lui-même.
2
Instrumenter
L'agent applique le prompt d'intégration : middleware framework et/ou start_flow/start_step.
3
Mesurer
integration.quality renvoie un score 0–100, un niveau (EXCELLENT → BROKEN) et la liste des checks en échec avec des exemples de spans réels. L'agent lit les fixes suggérés et corrige.
4
Confirmer la connectivité
integration.host_health atteste que le SDK émet bien des signaux de présence (heartbeats) : connecté, silencieux, ou jamais vu. De quoi distinguer « mal instrumenté » de « pas déployé ».

Critère d'arrêt

L'intégration est saine quand integration.quality renvoie un niveau EXCELLENT avec alert_active: false, et que integration.host_health montre l'instance connectée. Tant que ce n'est pas le cas, l'agent itère.

La mise en service complète

Le prompt onboard-sia déroule tout le parcours. L'agent appelle journey.status au début et à chaque reprise : l'étape est recalculée à partir des données, rien n'est mémorisé.

1
Intégrer
L'agent pose le SDK, puis génère quelques tours. Il attend un volume de traces (20 étapes récentes au moins), pas un délai : la note est calculée à la demande. Il corrige jusqu'à une note récente d'au moins 95, sans contrôle critique en échec.
2
Compléter la gouvernance
L'agent lit le code et les vrais tours (traces.read), puis mène l'entretien de gouvernance. Vous répondez aux intentions métier, il propose le reste.
3
Essayer puis activer les juges
judges.try évalue les juges proposés sur des tours réels, brouillon compris, sans rien enregistrer. Chaque échec est rangé : gouvernance à compléter, intégration à corriger, lecture à revoir côté NiaOne, ou vrai problème du SIA. Les juges activés démarrent en observation : ils évaluent sans alerter, sauf les juges de sécurité critiques.
4
Valider dans la conversation
Pendant l'observation, l'agent applique les règles de comportement après votre accord (governance.apply_draft). La sécurité, la qualité, la description et la déclaration EU AI Act restent à valider dans NiaOne.
5
Activer les alertes
Quand plus aucun faux positif ne reste, vous activez les alertes, depuis l'agent (judges.go_live) ou depuis l'onglet Juges du SIA. Les modifications de gouvernance se valident ensuite dans NiaOne.

L'observation n'est possible qu'une fois

Un SIA dont un juge a déjà levé une alerte ne peut pas repasser en observation. Un SIA déjà surveillé en production n'est jamais rendu silencieux par un agent.

Clients supportés

Tout client parlant le protocole MCP sur transport Streamable HTTP : Claude Code et Cursor via .mcp.json, ou tout IDE/agent équivalent. Le libellé du serveur (niaone) et les scopes de la clé sont les seuls paramètres à adapter.

Premiers pas — créer un SIA et une clé Le catalogue des checks de qualité Troubleshooting — le SDK n'émet rien