@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "Clients MCP"
+description: "Connectez votre application native d'agent aux serveurs MCP locaux (claude-in-chrome, système de fichiers, dramaturge, etc.) afin que l'agent dispose de ses outils."
+---
+
+# Clients MCP
+
+**Cette page : donnez plus d'outils à votre agent.** Pointez une application native d'agent vers les serveurs MCP (locaux ou distants) afin que leurs outils s'affichent dans le chat de l'agent. Il s'agit de la direction _client_, l'image miroir de [MCP Protocol](/docs/mcp-protocol) (qui fait de votre application un _serveur_ MCP).
+
+| Si vous voulez…                                                                               | Lire                                     |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Connectez un agent/hôte externe à votre application                                           | [External Agents](/docs/external-agents) |
+| Donnez plus d'outils à votre agent (consommez d'autres serveurs MCP)                          | **Cette page** — Clients MCP             |
+| Créez des UI en ligne qui s'affichent dans Claude/ChatGPT                                     | [MCP Apps](/docs/mcp-apps)               |
+| Référence du serveur MCP de niveau inférieur (authentification, outils, montage personnalisé) | [MCP Protocol](/docs/mcp-protocol)       |
+
+Avec un seul fichier de configuration, chaque application native d'agent de votre espace de travail a accès aux outils fournis par les serveurs MCP sur votre machine : `claude-in-chrome` pour l'automatisation du navigateur, `@modelcontextprotocol/server-filesystem` pour la lecture de fichiers, `@playwright/mcp` pour les tests du navigateur et tout ce qui parle de MCP.
+
+Vous pouvez également utiliser [connect remote (HTTP) MCP servers at runtime](#remote-via-ui) (utilisateurs individuels ou organisations entières) sans modifier de fichier de configuration.
+
+Chaque source se résout en un seul **gestionnaire MCP** d'exécution, et chaque outil qu'il apprend atterrit dans le registre d'outils de l'agent sous un préfixe `mcp__<server-id>__<tool>` anti-collision — consultable intentionnellement via `tool-search`.
+
+```an-diagram title="Client direction: many sources, one tool registry" summary="Config files, env, and runtime UI all merge into the MCP manager; its tools appear prefixed and tool-searchable alongside your app's actions. This is the mirror of the server direction."
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">shared across apps</small></div><div class=\"diagram-box\" data-rough>App-root <code>mcp.config.json</code><br><small class=\"diagram-muted\">per-app override</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / production</small></div><div class=\"diagram-box\" data-rough>Remote via settings UI<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP manager</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent tool registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">discover by intent</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> La direction opposée : faire de _votre_ application un serveur MCP que d'autres hôtes consomment - se trouve dans [MCP Protocol](/docs/mcp-protocol) et [External Agents](/docs/external-agents).
+
+## Navigateur intégré et fonctionnalités d'utilisation de l'ordinateur {#built-in-capabilities}
+
+L'agent natif inclut des options de développement local pour les serveurs standard MCP courants.
+Ils sont désactivés par défaut et peuvent être activés par utilisateur ou par organisation uniquement
+lorsque l'application s'exécute localement. Ignorer les environnements d'exécution sans serveur de production et hébergés
+ces éléments intégrés même si d'anciennes lignes de paramètres existent, ainsi que les ressources de l'espace de travail
+l'arborescence ne les affiche pas comme ressources `mcp-servers/*.json` par défaut.
+
+| Capacité                       | ID du serveur     | Commande                                                                |
+| ------------------------------ | ----------------- | ----------------------------------------------------------------------- |
+| Outils de développement Chrome | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| Navigateur de dramaturge       | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| Utilisation de l'ordinateur    | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+Une seule fonctionnalité de navigateur peut être activée dans une étendue à la fois. L'activation de Chrome DevTools désactive Playwright pour ce même utilisateur ou cette même organisation, et l'activation de Playwright désactive Chrome DevTools.
+
+L'utilisation de l'ordinateur est réservée à macOS uniquement. Sur d'autres plates-formes, il est répertorié comme indisponible et est ignoré même si une ancienne ligne de paramètres le contient.
+
+Chrome DevTools utilise `--autoConnect` par défaut. Cela s'attache à une instance Chrome en cours d'exécution éligible ; il ne crée pas de profil de navigateur isolé et ne se connecte pas au profil habituel de l'utilisateur pour vous. Il nécessite Chrome 144+ avec le débogage à distance activé. Une configuration manuelle `browser-url` peut être ajoutée ultérieurement lorsqu'un déploiement nécessite un point de terminaison de débogage spécifique.
+
+Les éléments intégrés sont conservés dans la table `settings` du framework sous `u:<email>:mcp-builtin-capabilities` pour les bascules personnelles et `o:<orgId>:mcp-builtin-capabilities` pour les bascules d'équipe. Lorsqu'ils sont activés, ils fusionnent dans le gestionnaire d'exécution MCP avec le même format de visibilité étendue que les serveurs distants, par exemple `mcp__user_<emailhash>_playwright__*` ou `mcp__org_<orgId>_chrome-devtools__*`.
+
+### Notes de configuration destinées aux utilisateurs
+
+Utilisez une copie de configuration concise et explicite pour les éléments intégrés sensibles :
+
+- **Chrome DevTools** s'attache à une cible de débogage Chrome en cours d'exécution. Informez les utilisateurs
+  il est destiné aux tests du navigateur et à la vérification de la connexion, et il
+  peut nécessiter l'activation du débogage à distance de Chrome avant que les outils n'apparaissent.
+- **Playwright** lance un navigateur isolé. Recommandez-le pour les déterministes
+  Contrôle qualité lorsque le profil Chrome actif de l'utilisateur n'est pas requis.
+- **Utilisation de l'ordinateur** peut faire fonctionner des applications locales. Gardez-le désactivé par défaut, expliquez le
+  Invites d'enregistrement d'écran et d'accessibilité macOS, et demande avant de prendre
+  actions sensibles, tels que les achats, les modifications financières ou les modifications de compte.
+
+### Points de terminaison intégrés
+
+| Méthode | Itinéraire                   | Objectif                                                                                                       |
+| ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| GET     | `/_agent-native/mcp/builtin` | Répertoriez les fonctionnalités intégrées, les étendues activées, les identifiants fusionnés et l'état actuel. |
+| POST    | `/_agent-native/mcp/builtin` | Mettre à jour une étendue. Corps : `{ scope, enabledIds }` ou `{ scope, id, enabled }`.                        |
+
+## Ajout d'un serveur MCP local {#adding-a-server}
+
+Créez `mcp.config.json` à la racine de votre espace de travail (ou à la racine d'une application individuelle : la racine de l'espace de travail l'emporte lorsque les deux existent) :
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+La forme est petite : une carte `servers` saisie par identifiant de serveur, où chaque entrée est soit un lanceur stdio (`command` + `args` + `env` en option), soit une entrée `{ "type": "http", "url", "headers" }` distante.
+
+```an-annotated-code title="mcp.config.json, annotated"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "Server id", "note": "The key becomes the tool prefix: this server's tools surface as `mcp__claude-in-chrome__*` in the agent's registry, so they can't collide with your template's actions." },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` spawn a local binary. Stdio servers are intended for **local development** — they are a no-op in edge runtimes." },
+    { "lines": "6", "label": "Process env", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+Au prochain démarrage de l'application, vous verrez :
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+Les outils sont enregistrés dans le registre d'outils de l'agent avec le préfixe `mcp__<server-id>__<tool-name>` afin qu'ils ne puissent pas entrer en collision avec le actions de votre modèle. Ils sont également inclus dans `tool-search`, afin que les agents puissent découvrir intentionnellement les fonctionnalités MCP nouvellement connectées au lieu d'avoir besoin du préfixe exact du nom au départ.
+
+## Priorité de configuration {#precedence}
+
+La configuration MCP est résolue dans cet ordre, le premier match gagne :
+
+1. **Racine de l'espace de travail `mcp.config.json`** — détectée via `agent-native.workspaceCore` dans `package.json`. Partagé dans toutes les applications de l'espace de travail.
+2. **App-root `mcp.config.json`** — remplacement par application si vous ne souhaitez pas qu'un serveur MCP soit disponible dans chaque application.
+3. **`MCP_SERVERS` env var** — Chaîne JSON avec la même forme, pour CI/production où un fichier n'a pas de sens.
+
+## Déploiements en production : `MCP_SERVERS` {#mcp-servers-env}
+
+Pour les déploiements en production, préférez les serveurs distants HTTP MCP et définissez la configuration complète
+forme (ou la carte du serveur interne) en tant que variable d'environnement :
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` est analysé comme JSON, donc les espaces réservés `${...}` ne sont pas développés
+à l'intérieur de la chaîne. Si vous stockez le jeton dans un autre secret, développez-le avant
+écrire la valeur finale JSON.
+
+Les serveurs Stdio MCP génèrent des binaires locaux et sont destinés au développement local.
+Les outils MCP s'activent uniquement dans les environnements d'exécution Node – Cloudflare Workers et autres périphériques
+les cibles ignorent silencieusement MCP et continuent de fonctionner avec le reste de l'application
+normalement.
+
+## Détection automatique : `claude-in-chrome` {#autodetect}
+
+Si vous n'avez **pas** de `mcp.config.json` et que le binaire `claude-in-chrome-mcp` se trouve sur `PATH` (ou dans l'emplacement d'installation bien connu `~/.claude-in-chrome/bin/claude-in-chrome-mcp`), l'agent natif l'enregistre automatiquement en tant que serveur MCP par défaut. Configurez `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` pour vous désinscrire.
+
+Cela signifie que les utilisateurs qui ont installé l'extension claude-in-chrome obtiennent le contrôle du navigateur sur chaque application native d'agent qu'ils ouvrent sans aucune modification de configuration.
+
+## Serveurs MCP distants via les paramètres UI {#remote-via-ui}
+
+Les serveurs MCP (Model Context Protocol) offrent à votre agent de nouvelles capacités, comme la connexion à Zapier, Cloudflare, Composio ou aux outils internes de votre entreprise. Une fois connecté, l'agent peut utiliser ces outils tout comme ses outils intégrés.
+
+### Comment connecter un serveur MCP distant
+
+1. **Nom du serveur** — une courte étiquette pour votre propre référence (par exemple "zapier", "slack-tools").
+2. **URL** : le point de terminaison HTTPS que le fournisseur de serveur MCP vous a fourni (par exemple, `https://mcp.zapier.com/s/abc123/mcp`). Cela se trouve généralement dans le tableau de bord du fournisseur ou dans les documents d'intégration.
+3. **Description** (facultatif) : une note sur ce que fait ce serveur.
+4. **En-têtes** : informations d'authentification requises par le serveur, une par ligne. La plupart des serveurs ont besoin d'un en-tête `Authorization`. Exemple : `Authorization: Bearer sk-your-key-here`. Les documents du fournisseur vous indiqueront quoi mettre ici.
+
+Cliquez sur **Test** pour vérifier la connexion avant d'enregistrer. Si cela réussit, vous verrez le nombre d’outils disponibles. Cliquez sur **Connecter** pour l'ajouter.
+
+### Portée personnelle ou organisationnelle
+
+Deux étendues sont prises en charge :
+
+- **Personnel** : seul l'utilisateur connecté obtient les outils. Stocké en tant que paramètre de portée utilisateur.
+- **Équipe** : tous les membres de l'organisation active disposent des outils nécessaires. Les propriétaires et les administrateurs peuvent ajouter : les membres voient la liste en lecture seule. Stocké en tant que paramètre de portée de l'organisation.
+
+Ajoute et supprime le rechargement à chaud dans le gestionnaire MCP en cours d'exécution – pas de redémarrage du processus ni de redémarrage du serveur. Les nouveaux outils `mcp__<scope>-<name>__*` apparaissent à l'agent lors du message suivant et peuvent être recherchés via `tool-search`.
+
+Les HTTPS URL sont acceptés partout ; Le `http://` simple n'est autorisé que pour le `localhost` pendant le développement. L'authentification facultative est introduite sous la forme d'un jeton Bearer envoyé via `Authorization: Bearer …` à chaque demande.
+
+Sous le capot, ces serveurs sont conservés dans la table `settings` du framework sous la clé `u:<email>:mcp-servers-remote` (Personnel) ou `o:<orgId>:mcp-servers-remote` (Équipe) et fusionnés avec `mcp.config.json` au démarrage.
+
+### Points de terminaison HTTP
+
+| Méthode | Itinéraire                                            | Objectif                                                                                              |
+| ------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| GET     | `/_agent-native/mcp/servers`                          | Répertoriez les serveurs personnels et d'organisation de l'utilisateur actuel avec leur statut actif. |
+| POST    | `/_agent-native/mcp/servers`                          | Ajouter un serveur. Corps : `{ scope, name, url, headers?, description? }`.                           |
+| DELETE  | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Supprimez un serveur et reconfigurez le gestionnaire.                                                 |
+| POST    | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Exécutez à sec les outils de connexion et de liste du serveur existant.                               |
+| POST    | `/_agent-native/mcp/servers/test`                     | Exécutez à sec un URL arbitraire avant de persister. Corps : `{ url, headers? }`.                     |
+
+Les serveurs Stdio ne fonctionnent toujours pas en dehors des environnements d'exécution Node, mais les serveurs distants HTTP MCP fonctionnent dans n'importe quel environnement avec `fetch`, y compris les versions de production de bureau.
+
+## Serveurs MCP partagés via un hub {#hub}
+
+Si votre espace de travail exécute plusieurs applications natives d'agent (par exemple, dispatch + mail + clips), vous pouvez configurer **une** application comme hub et demander aux autres d'extraire automatiquement ses serveurs MCP de portée organisationnelle. Pas de copier-coller par application des URL et des jetons au porteur. Voir [Multi-App Workspace](/docs/multi-app-workspace) pour l'approche canonique utilisant les ressources MCP de l'espace de travail Dispatch.
+
+Dispatch est le hub conventionnel : il assure déjà la coordination entre les applications.
+
+```an-diagram title="Hub model: one app serves org-scope MCP servers" summary="Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">org-scope MCP servers</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">pull + merge each ~60s</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+Pour les nouvelles configurations d'espace de travail, préférez **Répartir les ressources MCP de l'espace de travail** lorsque vous
+vous souhaitez le même modèle d'attribution pour toutes les applications et celles sélectionnées que celui utilisé par l'espace de travail skills,
+instructions et ressources de référence. Ajoutez une ressource d'espace de travail avec :
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Enregistrez-le sous `mcp-servers/<name>.json` avec le type `mcp-server`. Toutes les applications
+les ressources sont chargées par chaque application d'espace de travail ; les ressources sélectionnées se chargent uniquement dans
+applications avec une subvention Dispatch active. Les espaces réservés secrets sont résolus depuis l'application
+magasin secret, alors placez les jetons de porteur bruts dans Dispatch Vault et référencez-les
+avec `${keys.NAME}` au lieu de les stocker dans le corps de la ressource.
+
+Les applications actualisent leur configuration MCP fusionnée environ une fois par minute, donc une ressource centrale
+les modifications, les modifications d'autorisation et les suppressions prennent effet sans déploiement. Définir
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` pour désactiver cette actualisation en arrière-plan, ou
+définissez-le sur une valeur d'au moins `5000` millisecondes pour régler l'intervalle.
+
+L'ancien mode hub ci-dessous reste utile pour le « partage grossier de chaque MCP de portée organisationnelle
+serveur de Dispatch" et pour les déploiements qui utilisent déjà le MCP
+paramètres UI comme source de vérité.
+
+### 1. Activer Hub-Serve sur l'application Hub (répartition)
+
+Définissez une variable d'environnement dans le déploiement de dispatch :
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch monte désormais `GET /_agent-native/mcp/hub/servers` qui renvoie chaque serveur MCP de portée organisationnelle stocké dans sa table `settings`, avec les en-têtes URL + complets, authentifiés par le jeton.
+
+### 2. Applications consommatrices de points au niveau du hub
+
+Défini sur chaque consommateur (mail, clips, peu importe) :
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+Au démarrage, chaque consommateur extrait la liste des serveurs du hub et la fusionne dans son propre gestionnaire MCP. Les outils apparaissent à l'agent sous la forme `mcp__hub_<orgId>_<name>__*`, distincts du propre `mcp__org_…` local du consommateur, il n'y a donc pas de collision.
+
+### 3. Ce qui est partagé
+
+Seuls les serveurs **org-scope** sont partagés. Les serveurs au niveau utilisateur (personnels) restent la propriété de l'utilisateur qui les a ajoutés : le hub ne réexpose jamais les informations d'identification personnelles dans les applications.
+
+Les réponses du Hub incluent les en-têtes d'authentification complets (jetons du porteur, etc.). Le transport est HTTPS, le point de terminaison nécessite le secret partagé et il ne renvoie que les lignes de portée de l'organisation – traitez le hub URL + le jeton comme un identifiant de base de données.
+
+### 4. Rechargement à chaud ou redémarrage
+
+Le local UI ajoute un rechargement à chaud dans chaque application via `McpClientManager.reconfigure()` — pas de redémarrage. Les serveurs provenant du hub sont récupérés par la même actualisation périodique en arrière-plan (environ 60 s, réglable ou désactivable via `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS`) que celle utilisée par le chemin des ressources de l'espace de travail, de sorte que les modifications apportées dans Dispatch se propagent à toutes les applications grand public en une minute environ sans redémarrage. De plus, toute mutation locale dans une application grand public déclenche immédiatement une reconfiguration de cette application.
+
+### Résumé des points de terminaison
+
+| Méthode | Itinéraire                       | Objectif                                                                                                                                                         |
+| ------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET     | `/_agent-native/mcp/hub/servers` | Servez tous les serveurs de l'organisation avec des crédits complets (dépendants du porteur, montés uniquement lorsque `AGENT_NATIVE_MCP_HUB_TOKEN` est défini). |
+| GET     | `/_agent-native/mcp/hub/status`  | Renvoie `{ serving, consuming, hubUrl }` pour les paramètres de la carte UI.                                                                                     |
+
+## Statut de l'itinéraire {#status-route}
+
+Chaque application expose `GET /_agent-native/mcp/status` pour les outils et l'intégration :
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP client status for tooling and onboarding",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+Utilisez ceci pour créer des conseils d'intégration « Claude-in-Chrome détecté – votre agent peut désormais piloter Chrome » ou pour déboguer les problèmes de connexion MCP.
+
+## Modes de défaillance {#failures}
+
+Les pannes individuelles du serveur MCP ne mettent jamais l'agent hors service :
+
+- Un `command` mal configuré → le serveur est ignoré, son erreur apparaît dans `/mcp/status` sous `errors.<server-id>` et tous les autres serveurs continuent de fonctionner.
+- Le MCP SDK est absent du `node_modules` → toutes les fonctionnalités du MCP sont ignorées avec un avertissement ; Le chat d'agent continue de fonctionner sans aucun outil MCP.
+- S'exécuter dans un environnement d'exécution Edge → Le client MCP ne fonctionne pas.
+
+L'agent natif démarrera toujours ; une configuration MCP cassée signifie simplement moins d'outils.
+
+## Sécurité {#security}
+
+Les outils MCP s'exécutent sur votre ordinateur avec les autorisations dont dispose le processus généré. Traitez `mcp.config.json` comme n'importe quelle autre liste d'exécutables que vous êtes prêt à laisser conduire l'agent. Les outils des serveurs MCP apparaissent dans la boucle d'utilisation des outils de l'agent, tout comme le actions de votre modèle, alors assurez-vous de faire confiance à chaque serveur que vous configurez.

package/docs/content/locales/fr-FR/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "Protocole MCP"
+description: "Exposez votre application native d'agent en tant que serveur MCP distant afin que Claude, ChatGPT, Claude Code, Cursor et d'autres outils d'IA puissent appeler directement le actions de votre application."
+---
+
+# Protocole MCP
+
+**Cette page : référence du serveur MCP de niveau inférieur.** Comment chaque application native d'agent expose son actions sur MCP : le point de terminaison monté automatiquement, les modes d'authentification, la surface `tools/call`/`ask-agent` et le montage personnalisé. Accédez-y lorsque vous avez besoin de composants internes du serveur ; pour connecter un hôte, commencez par [External Agents](/docs/external-agents).
+
+| Si vous voulez…                                                                               | Lire                                     |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Connectez un agent/hôte externe à votre application                                           | [External Agents](/docs/external-agents) |
+| Donnez plus d'outils à votre agent (consommez d'autres serveurs MCP)                          | [MCP Clients](/docs/mcp-clients)         |
+| Créez des UI en ligne qui s'affichent dans Claude/ChatGPT                                     | [MCP Apps](/docs/mcp-apps)               |
+| Référence du serveur MCP de niveau inférieur (authentification, outils, montage personnalisé) | **Cette page** — Protocole MCP           |
+
+Chaque application native d'agent expose automatiquement un serveur distant MCP (Model Context Protocol), de sorte que les outils d'IA externes tels que Claude, les applications MCP personnalisées ChatGPT, le code Claude, le curseur, le Codex et le VS Code GitHub Copilot peuvent découvrir et appeler directement le actions de votre application — aucun code supplémentaire n'est nécessaire. Si votre objectif est de _connecter_ l'un de ces hôtes à une application hébergée, [External Agents](/docs/external-agents) couvre le connecteur Dispatch unique recommandé, les URL par application, les OAuth, les applications MCP en ligne UI et les liens profonds. Cette page documente ce qui se trouve en dessous.
+
+## Vue d'ensemble {#overview}
+
+MCP est le protocole standard pour connecter les outils d'IA à des capacités externes. Lorsque vous déployez une application native d'agent, elle monte automatiquement un point de terminaison MCP aux côtés du point de terminaison A2A existant. Tout client compatible MCP peut se connecter et utiliser les outils de votre application.
+
+Concepts clés :
+
+- **Monté automatiquement** – chaque application obtient `/_agent-native/mcp` gratuitement, aucune configuration requise
+- **Streamable HTTP** : utilise le transport moderne MCP par rapport au HTTP standard (POST + SSE)
+- **Même actions** : exactement le même registre d'actions qui alimente le chat des agents et A2A
+- **Outil `ask-agent`** — un méta-outil qui délègue à la boucle d'agent complète les tâches complexes
+- **Applications MCP** — actions peut annoncer des ressources UI interactives via l'extension officielle `io.modelcontextprotocol/ui`
+- **MCP à distance standard OAuth** — Découverte OAuth 2.1, enregistrement client dynamique, code d'autorisation + PKCE, rotation du jeton d'actualisation
+- **Bearer auth fallback** : utilise `ACCESS_TOKEN`, `ACCESS_TOKENS` ou des JWT créés par connexion pour les clients qui ne peuvent pas exécuter OAuth
+
+```an-diagram title="Your app as an MCP server" summary="External hosts connect over Streamable HTTP. Each action is one tool; ask-agent delegates to the full agent loop."
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP contre A2A {#mcp-vs-a2a}
+
+Les deux protocoles sont montés automatiquement. Utilisez celui qui correspond à votre cas d'utilisation :
+
+|                          | MCP                                                                     | A2A                                            |
+| ------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------- |
+| **Idéal pour**           | Outils externes appelant votre application                              | Communication d'agent à agent                  |
+| **Protocole**            | MCP HTTP diffusable                                                     | JSON-RPC 2.0                                   |
+| **Découverte d'outils**  | `tools/list`                                                            | Carte d'agent à `/.well-known/agent-card.json` |
+| **Point de terminaison** | `/_agent-native/mcp`                                                    | `/_agent-native/a2a`                           |
+| **Supporté par**         | Claude, ChatGPT, Claude Code, Cursor, Codex, Cowork et autres hôtes MCP | Autres applications natives pour agents        |
+| **Exécution**            | Appels d'outils directs (pas de LLM supplémentaire)                     | Boucle d'agent complète (raisonnement LLM)     |
+
+Vous pouvez également utiliser l'outil `ask-agent` MCP pour tirer le meilleur parti des deux mondes : appelez-le à partir du code Claude et laissez l'agent de votre application raisonner sur des tâches complexes.
+
+## Configuration manuelle du client MCP {#manual-config}
+
+Pour la configuration recommandée en une seule commande, utilisez [External Agents](/docs/external-agents). Si vous écrivez manuellement la configuration MCP pour un client compatible OAuth, ajoutez votre application en tant que serveur MCP distant sans en-têtes statiques :
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+Ou écrivez l'entrée à la main dans `.mcp.json` (portée du projet) ou `~/.claude.json` (portée utilisateur) :
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Exécutez ensuite `/mcp` dans le code Claude et choisissez **Authentifier**. Pour les clients qui ne peuvent pas exécuter MCP OAuth à distance, utilisez la page Connecter ou une entrée de jeton de porteur statique avec `headers.Authorization`. Une fois authentifié, vous pouvez utiliser les outils de votre application naturellement :
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## Connexion à partir d'autres clients MCP {#other-clients}
+
+Tout client MCP prenant en charge le transport Streamable HTTP peut se connecter. Le point final est :
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+Le serveur prend en charge la négociation standard MCP : `initialize` → `initialized` → `tools/list` → `tools/call`.
+
+```an-api title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes."
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP Streamable HTTP endpoint",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+Si une action déclare `mcpApp`, le serveur annonce également l'extension officielle des applications MCP (`io.modelcontextprotocol/ui`) et prend en charge `resources/list`, `resources/templates/list` et `resources/read` pour la ressource d'application. Les hôtes qui restituent les applications MCP peuvent afficher le UI en ligne ; les hôtes qui ne le font pas peuvent toujours appeler l'outil et utiliser la solution de secours par lien profond. Les produits UI doivent utiliser `embedApp()` afin que la surface en ligne soit la véritable route de l'application React, ou une route ciblée qui restitue un composant React partagé tel qu'un graphique Analytics, et non une implémentation distincte de HTML. Le serveur émet à la fois les métadonnées standard des applications MCP et les métadonnées de compatibilité des applications ChatGPT SDK afin que les hôtes compatibles avec les applications puissent trouver la même ressource `ui://`. La matrice d'extension officielle actuelle comprend Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT et Cursor ; La prise en charge de l'hôte varie selon la version et le forfait, utilisez donc le [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) pour obtenir des conseils destinés à l'utilisateur.
+
+### Pont d'intégration d'application MCP {#mcp-app-embed-bridge}
+
+`embedApp()` est le premier assistant d'application MCP de bas niveau pour URL : il lance une application signée
+acheminement en ligne via une transplantation (Claude), un cadre contrôlé (ChatGPT) ou direct
+navigation, assure la médiation de l'hôte actions sur le pont `ui/*` JSON-RPC (et le
+Relais postMessage `agentNative.mcpHost.*` pour le chemin de trame contrôlé), et
+limite la hauteur du shell de ressources afin qu'un itinéraire d'application complète ne s'affiche pas comme un
+artefact de discussion surdimensionné.
+
+Voir [MCP Apps](/docs/mcp-apps#mcp-app-bridge) pour plus de détails sur le pont intégré : transplantation par rapport au cadre contrôlé, les tables `ui/*` et postMessage, `create_embed_session` / `embedStartUrl`, CSP et les règles de domaine, l'intégration de l'extension `srcDoc`, le serrage de la hauteur et le client de pont hôte API.
+
+## Outils {#tools}
+
+Chaque appelant reçoit un **catalogue compact par défaut** (application déclarée par modèle actions plus les applications intégrées), avec la surface d'action complète servie uniquement sur adhésion explicite et `tool-search` toujours disponible pour atteindre le reste. Voir [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers) pour l'explication complète.
+
+Chaque action correspond directement à un outil MCP :
+
+| Propriété d'action | Propriété de l'outil MCP |
+| ------------------ | ------------------------ |
+| `tool.description` | `description`            |
+| `tool.parameters`  | `inputSchema`            |
+| Nom de l'action    | Nom de l'outil           |
+
+Lorsque `mcpApp` est présent, l'entrée d'outil inclut également `_meta.ui.resourceUri`, `_meta["ui/resourceUri"]` et `_meta["openai/outputTemplate"]`, et la ressource `ui://` correspondante est renvoyée sous la forme `text/html;profile=mcp-app`.
+
+### L'outil `ask-agent` {#ask-agent}
+
+En plus des outils d'action individuels, chaque serveur MCP comprend un méta-outil `ask-agent`. Cela envoie un message en langage naturel à l'agent IA de l'application et renvoie la réponse.
+
+Utilisez `ask-agent` pour des tâches complexes qui bénéficient du raisonnement et du contexte de l'agent :
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+L'agent exécute la même boucle que le chat interactif : il peut appeler plusieurs outils, raisonner sur le contexte et produire une réponse réfléchie.
+
+## Authentification {#authentication}
+
+Le point de terminaison MCP prend en charge le modèle distant standard MCP OAuth, ainsi que le remplacement du jeton de support existant :
+
+| Mode                                  | Comment ça marche                                                                                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| MCP standard OAuth                    | Le client découvre l'authentification de `WWW-Authenticate`, s'enregistre, exécute PKCE et envoie `Authorization: Bearer <access-token>` |
+| JWT créé par Connect                  | `npx @agent-native/core@latest connect` / la page Connect crée un JWT révocable par utilisateur                                          |
+| `ACCESS_TOKEN`                        | Jeton de support statique — le client envoie `Authorization: Bearer <token>`                                                             |
+| `ACCESS_TOKENS`                       | Liste de jetons de support statiques valides, séparés par des virgules                                                                   |
+| `A2A_SECRET`                          | Authentification basée sur JWT : les jetons sont vérifiés cryptographiquement                                                            |
+| _(aucun défini, bouclage uniquement)_ | Aucune authentification requise pour les sondes de développement locales                                                                 |
+
+Pour les hôtes MCP compatibles OAuth, configurez le serveur distant URL sans en-têtes statiques :
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+La première requête MCP non authentifiée reçoit :
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+Points de terminaison de découverte :
+
+| Point de terminaison                      | Objectif                                                   |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| `/.well-known/oauth-protected-resource`   | Métadonnées de ressources protégées RFC 9728               |
+| `/.well-known/oauth-authorization-server` | Métadonnées du serveur d'autorisation OAuth                |
+| `/_agent-native/mcp/oauth/register`       | Inscription dynamique du client public                     |
+| `/_agent-native/mcp/oauth/authorize`      | Autorisation du navigateur + consentement                  |
+| `/_agent-native/mcp/oauth/token`          | Accords de code d'autorisation et de jeton d'actualisation |
+
+```an-diagram title="OAuth discovery flow" summary="A 401 kicks off discovery, registration, and a PKCE authorize → token exchange. The Bearer token is audience-bound and scoped."
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">audience-bound · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+Les jetons d'accès sont des JWT signés dont l'audience est exactement la ressource MCP URL. Le serveur n'accepte que les jetons émis pour lui-même et applique les étendues avant de lister/appeler les outils :
+
+| Portée      | Autorise                                                |
+| ----------- | ------------------------------------------------------- |
+| `mcp:read`  | actions en lecture seule                                |
+| `mcp:write` | mutation de actions et `ask-agent`                      |
+| `mcp:apps`  | Ressources d'applications MCP (ressources `ui://` HTML) |
+
+Les jetons d'actualisation sont stockés uniquement sous forme de hachages et font l'objet d'une rotation à chaque actualisation. `npx @agent-native/core@latest connect` écrit par défaut cette entrée OAuth uniquement URL pour les clients de code Claude ; conservez la page Connect, `npx @agent-native/core@latest connect --token <token>` et la configuration du support statique pour le proxy stdio local, les clients plus anciens et les flux d'urgence/débogage.
+
+## Configuration MCP personnalisée {#custom-setup}
+
+Le serveur MCP est monté automatiquement par le plugin agent-chat. Pour la plupart des applications, aucune configuration n'est nécessaire. Si vous avez besoin d'un comportement personnalisé, vous pouvez le monter manuellement dans un plugin serveur :
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## Exemple : analyses du code Claude {#example}
+
+Vous disposez d'une application d'analyse déployée sur `analytics.example.com`. À partir du code Claude :
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+Ou ajoutez-le à la main dans `.mcp.json` :
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Maintenant en code Claude :
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+Pour une analyse plus complexe :
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```