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.

Ce que le serveur expose

Cinq outils, tous cadrés par les permissions de votre clé (voir Scopes & sécurité plus bas), plus les guides du SDK en ressources lisibles par l'agent.

Ressources documentaires (l'agent les lit directement) : niaone://guide/typescript et niaone://guide/python : le guide d'intégration officiel, toujours à jour.

Configurer le client

1. 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. 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. 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 & sécurité

Une clé MCP ne porte que les permissions que vous cochez : c'est le principe du moindre privilège.

• La clé transite en Authorization: Bearer nia_mcp_… sur un transport HTTP, jamais dans le code.
• Elle est révocable à tout moment depuis Settings → MCP keys (et peut porter une expiration).
• Toutes les données remontées à l'agent sont cadrées au tenant ; les extraits de payload sont tronqués et étiquetés pour éviter toute injection de prompt.

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. 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. 2

   Instrumenter

   L'agent applique le prompt d'intégration : middleware framework et/ou start_flow/start_step.

3. 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. 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é ».

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.