@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/external-agents.md

@@ -0,0 +1,619 @@
+---
+title: "Agents externes : Claude, ChatGPT, Codex, Curseur, Cowork"
+description: "Connectez Claude, ChatGPT, Codex, Cursor, Claude Cowork ou tout hôte compatible MCP à une application native d'agent hébergée, puis transférez les artefacts aller-retour dans le UI en cours d'exécution avec les applications MCP et les liens profonds."
+search: "Claude ChatGPT Claude Code Codex Curseur Claude Cowork MCP Applications agent natif connecter outils d'agent local agents externes"
+---
+
+# Agents externes
+
+**Cette page : connectez un agent externe ou un hôte MCP à votre application.** Utilisez-la lorsque Claude, ChatGPT, Codex, Cursor, Claude Cowork ou un autre hôte compatible MCP doit piloter une application native d'agent hébergé et renvoyer le résultat dans le UI en cours d'exécution.
+
+| Si vous voulez…                                                                               | Lire                               |
+| --------------------------------------------------------------------------------------------- | ---------------------------------- |
+| Connectez un agent/hôte externe à votre application                                           | **Cette page** — Agents externes   |
+| Donnez plus d'outils à votre agent (utilisez 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é) | [MCP Protocol](/docs/mcp-protocol) |
+
+Une application agent native est accessible par n'importe quel hôte compatible MCP : Claude, Claude Desktop, Claude Code, ChatGPT applications MCP personnalisées, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam et les futurs clients qui implémentent le norme. Les agents externes sont excellents pour produire des artefacts (un brouillon, un événement, un tableau de bord) mais ils résident souvent dans un terminal ou une autre application. Sans pont, l'utilisateur obtient un mur de JSON et doit aller chercher la chose.
+
+Le pont d'agent externe ferme la boucle. Tout d'abord, vous connectez votre propre agent à une application **hébergée**, soit en collant le MCP URL distant de l'application dans un hôte de discussion comme Claude ou ChatGPT, soit en exécutant le flux de développeur CLI pour les agents de codage locaux. Ensuite, l'agent effectue le travail sur MCP et remet à l'utilisateur soit une **application MCP** UI en ligne sur des hôtes compatibles, soit un seul lien **"Ouvrir dans <app> →"** qui ouvre la véritable application axée sur exactement ce qui a été produit. Il réutilise le contrat `navigate` / `application_state` existant, le UI se vide déjà toutes les 2 secondes (voir [Context Awareness](/docs/context-awareness)) — il n'y a pas de deuxième mécanisme de navigation.
+
+```an-diagram title="The external-agent round-trip" summary="An external host calls a tool over MCP; the app returns an artifact plus an Open link. Clicking it resolves the browser session and focuses the artifact in the running UI — the link carries no privileged state."
+{
+  "html": "<div class=\"xa-trip\"><div class=\"diagram-box\" data-rough>External host<br><small class=\"diagram-muted\">Claude &middot; ChatGPT &middot; Codex &middot; Cursor</small></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 tool call</span><small class=\"diagram-muted\">e.g. <code>manage-draft</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>App produces artifact<br><small class=\"diagram-muted\">+ <code>Open in &lt;app&gt; &rarr;</code> deep link / MCP App</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>User clicks link</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill ok\"><code>/_agent-native/open</code></span><small class=\"diagram-muted\">resolves the <strong>browser</strong> session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes <code>navigate</code> app-state<br><small class=\"diagram-muted\">UI focuses the artifact</small></div></div>",
+  "css": ".xa-trip{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.xa-trip .center{display:flex;flex-direction:column;align-items:center;gap:4px}.xa-trip .diagram-arrow{font-size:22px;line-height:1}.xa-trip code{font-size:.85em}"
+}
+```
+
+La règle d'identité est la charnière de sécurité : le lien est simplement `view` + identifiants d'enregistrement + filtres, et l'écriture `navigate` ciblant l'enregistrement s'adresse à toute personne connectée au **navigateur** – jamais au jeton MCP de l'agent externe. C'est pourquoi le lien peut être collé en toute sécurité dans un terminal ou dans une transcription de discussion.
+
+## De quel chemin d'agent avez-vous besoin ? {#which-agent-path}
+
+- **Hôte MCP externe :** utilisez cette page lorsque Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code ou un autre hôte compatible MCP doit appeler votre application native d'agent hébergée.
+- **Votre propre environnement d'exécution derrière le chat Agent-Native :** consultez [Agent Surfaces](/docs/agent-surfaces#byo-agent) et [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) lorsqu'un agent créé avec un autre framework devrait alimenter `<AssistantChat runtime={...}>`.
+- **Votre application utilisant les outils MCP :** consultez [MCP Clients](/docs/mcp-clients) lorsqu'une application native d'agent doit appeler des outils exposés par un autre serveur MCP.
+- **Une autre application ou un autre agent via A2A :** utilisez [Agent Mentions](/docs/agent-mentions) et [A2A](/docs/a2a-protocol) lorsque les applications natives d'agent doivent se découvrir et se déléguer mutuellement.
+- **Sous-agents personnalisés locaux :** utilisez [Workspace](/docs/workspace) lorsque vous souhaitez des profils d'agent personnalisés dans l'espace de travail natif de l'agent lui-même.
+
+## Configuration facile {#easy-setup}
+
+Ajoutez un connecteur MCP distant à l'hôte sur lequel vous souhaitez utiliser Agent-Native.
+
+Pour le travail dans un espace de travail ou entre applications, utilisez Dispatch :
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dispatch est la passerelle unique pour Mail, Calendrier, Analytics, Brain et votre
+applications d'espace de travail. Sur la page **Agents** de Dispatch, choisissez si la passerelle peut
+atteindre toutes les applications ou uniquement les applications sélectionnées. L'hôte connecté obtient alors
+`list_apps`, `ask_app` et `open_app`, filtrés selon cet ensemble accordé.
+
+Pour une application intentionnellement isolée, utilisez cette application directement :
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+https://<your-app>.agent-native.com/_agent-native/mcp
+```
+
+Chaque application hébergée dispose également d'une page d'aide à l'adresse
+`https://<app>/_agent-native/mcp/connect` avec le URL copiable et
+Onglets spécifiques à l'hôte pour Claude, ChatGPT, Cursor, Claude Code, Codex et autres.
+
+### Claude et ChatGPT OAuth {#oauth}
+
+Claude / Claude Desktop : ajoutez un connecteur personnalisé, collez le MCP URL, cliquez
+**Connectez-vous**, connectez-vous avec votre compte Agent-Native, approuvez les scopes MCP,
+et activez le connecteur dans un chat. Le code Claude utilise le même URL : ajoutez-le en tant que
+Serveur HTTP MCP distant, exécutez `/mcp`, puis choisissez **Authentifier**.
+
+ChatGPT : utilisez un espace de travail où se trouvent des connecteurs MCP personnalisés ou des applications en mode développeur
+activé, créez un connecteur/une application personnalisé, collez le même MCP URL, choisissez OAuth,
+analysez/découvrez les outils, connectez-vous avec Agent-Native, approuvez les étendues et activez
+le connecteur dans une discussion.
+
+Les subventions OAuth sont par hôte et par utilisateur. L'hôte stocke les jetons et
+intervient dans les appels d'outils/ressources, de sorte que les aperçus de l'application MCP en ligne ne reçoivent jamais de données brutes
+Jetons OAuth. ChatGPT peut conserver un outil de connecteur révisé ou publié
+instantané jusqu'à ce que vous l'actualisiez/le révisiez à nouveau, donc analysez à nouveau le connecteur après MCP
+ou de l'application MCP. Si vous disposez encore d'anciens connecteurs par application
+activé avec Dispatch, actualisez ou reconnectez chaque connecteur obsolète ; mise à jour
+Dispatch ne réécrit pas le calendrier/courrier/etc mis en cache de ChatGPT ou Claude.
+instantanés. Les portées sont :
+
+| Portée      | Ce qu'il permet                                                           |
+| ----------- | ------------------------------------------------------------------------- |
+| `mcp:read`  | Outils en lecture seule et découverte d'outils/ressources                 |
+| `mcp:write` | Rédaction, mise à jour et autres actions en mutation                      |
+| `mcp:apps`  | Applications MCP en ligne, graphiques, tableaux de bord, brouillons et UI |
+
+Cursor, Goose, Postman, MCPJam et VS Code GitHub Copilot utilisent la même télécommande
+MCP URL via leur propre serveur MCP UI lorsque leur version prend en charge les OAuth distants
+Serveurs MCP.
+
+### Invite de test rapide {#quick-test}
+
+Une fois connecté, essayez l'une des solutions suivantes :
+
+```text
+Use Agent-Native Analytics to generate a weekly conversion-rate bar chart and show it inline.
+```
+
+```text
+Use Agent-Native Mail to draft a short follow-up email to me, but do not send it.
+```
+
+Dans les hôtes qui prennent en charge les applications MCP, Analytics peut afficher en ligne le tableau de bord réel et les itinéraires d'analyse, et Mail peut afficher en ligne le véritable tableau de bord UI pour révision du brouillon. Sur les hôtes qui n'affichent pas les applications MCP, le même appel d'outil renvoie toujours un lien profond tel que **Ouvrir le brouillon dans Mail →** ou **Ouvrir le tableau de bord dans Analytics →**.
+
+## Configuration avancée : agents locaux {#connect}
+
+Utilisez ce flux pour les clients d'agent locaux sur votre ordinateur : Code Claude, Code Claude CLI, Codex, Claude Cowork, Cursor, OpenCode et GitHub Copilot/VS Code. Cursor et d'autres clients natifs OAuth peuvent également utiliser le flux Paste-URL ci-dessus lorsque leur UI prend en charge le MCP OAuth distant.
+
+Exécutez la commande de connexion via npm :
+
+```bash
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
+```
+
+La commande demande quels clients d'agent local doivent recevoir la configuration MCP. Tous les clients sont présélectionnés une première fois ; une fois votre choix effectué, la sélection est enregistrée dans `~/.agent-native/connect.json` afin que la prochaine exécution puisse la réutiliser avec Entrée, ou vous pouvez modifier les éléments cochés.
+
+Pour le code Claude, le code Claude, le code CLI, Cursor, OpenCode et le code copilote/VS GitHub, `connect` écrit une entrée distante standard HTTP MCP sans en-têtes statiques. Redémarrez le client et authentifiez-vous à partir de son MCP UI lorsque vous y êtes invité. Pour Codex et Claude Cowork, `connect` utilise le flux de code de périphérique de compatibilité : il ouvre votre navigateur au niveau de l'application, vous cliquez une fois sur **Autoriser** et la commande écrit une entrée de jeton de porteur étendue. Si vous choisissez un mélange de clients, cela fait les deux.
+
+Laissez la commande `connect` exécutée jusqu'à ce que l'approbation du navigateur soit terminée. Si le
+le processus d'attente est arrêté plus tôt, l'approbation peut réussir dans le navigateur mais
+la configuration du client local ne recevra pas le jeton.
+
+Si vous avez déjà connecté le code Claude via l'ancien flux de jeton de support, exécutez simplement à nouveau la même commande `npx @agent-native/core@latest connect ... --client claude-code`. Le CLI remplace les anciens en-têtes `Authorization` par l'entrée OAuth uniquement URL et vous demande de vous réauthentifier à partir de `/mcp`.
+
+| Client local                  | Config écrite par `connect`                                 | Flux d'authentification                                     |
+| ----------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
+| Code Claude / Code Claude CLI | `.mcp.json` ou `~/.claude.json`, selon `--scope`            | Télécommande standard MCP OAuth dans le `/mcp` UI de Claude |
+| Curseur                       | `.cursor/mcp.json` ou `~/.cursor/mcp.json`                  | Télécommande standard MCP OAuth dans MCP UI du curseur      |
+| OpenCode                      | `opencode.json` ou `~/.config/opencode/opencode.json`       | Télécommande standard MCP OAuth dans MCP UI d'OpenCode      |
+| Copilote GitHub / Code VS     | Configuration MCP utilisateur `.vscode/mcp.json` ou VS Code | Télécommande standard MCP OAuth dans MCP UI de VS Code      |
+| Codex                         | `$CODEX_HOME/config.toml` ou `~/.codex/config.toml`         | Support de secours autorisé par le navigateur               |
+| Cotravail Claude              | `~/.cowork/mcp.json` utilisant la forme Claude Code MCP     | Support de secours autorisé par le navigateur               |
+
+Redémarrez le client agent après la connexion afin qu'il récupère le nouveau serveur MCP ; Les clients natifs OAuth peuvent alors vous inviter à vous authentifier à partir de leur MCP UI.
+
+Lors du dépannage de la configuration locale de MCP, expurgez `Authorization`, `http_headers`,
+et les valeurs des jetons avant de partager les journaux. N'utilisez pas de boucles brutes comme substitut à un
+héberger une session MCP ; après la connexion, utilisez les outils exposés à l'hôte ou redémarrez le
+client si le nouveau serveur n'est pas encore visible.
+
+Utilisez `--client codex` (ou `--client claude-code`, `--client claude-code-cli`, `--client cursor`, `--client opencode`, `--client github-copilot`, `--client cowork`, `--client all`) pour ignorer le sélecteur de scripts ou d'installations ponctuelles.
+
+L'application propriétaire skills installe les instructions et le connecteur MCP hébergé avec le Agent Native CLI :
+
+```bash
+npx @agent-native/core@latest skills add assets              # alias: image-generation
+```
+
+Le chemin Vercel/open Skills CLI est également disponible lorsque vous souhaitez uniquement du portable
+instructions :
+
+```bash
+npx skills@latest add BuilderIO/agent-native --skill assets
+```
+
+Le `skills` brut CLI installe uniquement les fichiers `SKILL.md` ; les clients locaux MCP sont toujours
+besoin d'un connecteur tel que `npx @agent-native/core@latest connect https://assets.agent-native.com`.
+
+| Compétence | Alias              | Pour                       |
+| ---------- | ------------------ | -------------------------- |
+| `assets`   | `image-generation` | génération d'images/vidéos |
+
+La sélection de clients par défaut concerne tous les clients locaux pris en charge ; ajoutez `--client codex`, `--client claude-code` ou une autre cible spécifique pour affiner la configuration. Les hôtes en ligne (ChatGPT, Claude.ai, chat principal du bureau Claude) affichent la grille de sélection/variante dans le chat ; Les hôtes CLI/lien uniquement (Codex, Code Claude, onglet « Code » du bureau Claude) renvoient un lien « Ouvrir dans… → » où l'utilisateur sélectionne dans le navigateur et colle un résumé du transfert.
+
+Lorsque vous avez vraiment besoin d'une application isolée au lieu de la passerelle d'espace de travail de Dispatch,
+exécutez la même commande avec l'hôte de cette application :
+
+```bash
+npx @agent-native/core@latest connect https://mail.agent-native.com
+```
+
+`connect --all` existe toujours pour les anciennes configurations de clients par application, mais il est nouveau
+Les configurations d'espace de travail doivent préférer le connecteur Dispatch unique.
+
+La connexion est **par utilisateur, limitée et révocable**. Dans le chemin OAuth, l'hôte stocke les jetons après l'authentification `/mcp` ; dans le chemin de secours, la session de navigateur avec laquelle vous avez autorisé est l'identité sous laquelle l'agent agit. Rien n'expose le secret partagé du déploiement.
+
+### Ré-authentification après un 401 {#reconnect}
+
+Une fois connecté, l'authentification doit persister à long terme : les jetons d'accès durent 30 jours par défaut (remplacement par `MCP_OAUTH_ACCESS_TOKEN_TTL` sur le serveur, par exemple `7d` ou `12h`) avec une fenêtre d'actualisation glissante de 365 jours, les 401 aléatoires devraient donc être rares. Lorsque cela se produit, utilisez la commande légère de reconnexion plutôt que de réinstaller :
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect` trouve toute entrée de configuration MCP dont URL se termine par `/_agent-native/mcp` pour l'hôte donné et le client sélectionné (correspondant à URL quel que soit le nom du connecteur), puis actualise ou remplace le matériel d'authentification sans toucher à votre skills installé ni réexécuter le flux d'installation complet. Transmettez l'application de base URL (par exemple `https://plan.agent-native.com`) — le suffixe `/_agent-native/mcp` est déduit. L'authentification et le chargement des outils se font par client, alors redémarrez/rechargez ce client par la suite ; Codex a besoin d'une nouvelle session avant que les outils nouvellement chargés n'apparaissent.
+
+Dans le code Claude, le chemin UI équivalent est : exécutez `/mcp` et choisissez **Authentifier** (ou **Reconnecter**) pour le connecteur concerné.
+
+Ne réinstallez jamais la compétence à partir de zéro juste pour réparer un 401 : `reconnect` est le bon outil.
+
+### Page de secours de connexion {#connect-page-fallback}
+
+Pour les clients MCP qui ne peuvent pas ajouter directement un OAuth distant URL, ouvrez l'application dans votre navigateur et utilisez son offre **Connect** (servie sur `https://<app>/_agent-native/mcp/connect`). Une fois connecté, cliquez sur **Connecter/Autoriser**. La page vous remet soit un lien profond en un clic qui configure un agent détecté, soit un bloc `.mcp.json` prêt à coller :
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
+
+Redémarrez le client agent après la connexion afin qu'il récupère le nouveau serveur MCP.
+
+Utilisez ce bloc support manuel pour les clients MCP qui ne peuvent pas terminer le flux distant standard MCP OAuth, ou pour un débogage ponctuel lorsque vous souhaitez explicitement coller un jeton.
+
+### Télécommande standard MCP OAuth {#standard-oauth}
+
+Les applications natives d'agent hébergées prennent également en charge le flux distant standard MCP OAuth. Pour les clients qui implémentent MCP OAuth, ajoutez le serveur distant HTTP URL sans en-têtes statiques :
+
+```bash
+claude mcp add --transport http agent-native \
+  https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Il s'agit de la même entrée réservée uniquement à URL que `npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code` écrit pour vous. Exécutez ensuite `/mcp` dans le code Claude et choisissez **Authentifier**. Le client découvre l'authentification à partir du défi `401 WWW-Authenticate` du serveur MCP, récupère `/.well-known/oauth-protected-resource` et `/.well-known/oauth-authorization-server`, enregistre dynamiquement un client OAuth public, ouvre la page d'autorisation de l'application et stocke le jeton résultant en toute sécurité. Les connecteurs en mode développeur ChatGPT utilisent le même serveur URL :
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Le flux OAuth est le code d'autorisation + PKCE avec rotation du jeton d'actualisation. Les jetons d'accès sont liés au public à la ressource MCP exacte URL et portent l'identité signée de l'utilisateur/de l'organisation. Ainsi, les appels d'outils, `resources/read` et MCP initiés par iframe de l'application `tools/call` s'exécutent tous via la même portée de locataire `runWithRequestContext` que le chemin JWT existant créé par la connexion. L'iframe ne reçoit jamais de jetons OAuth bruts ; l'hôte négocie les appels via la connexion authentifiée MCP.
+
+Les champs d'application actuels sont les suivants :
+
+| Portée      | Autorise                                                                                      |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| `mcp:read`  | MCP actions en lecture seule et découverte d'outils/ressources ordinaires                     |
+| `mcp:write` | mutation de actions et du méta-outil `ask-agent`                                              |
+| `mcp:apps`  | Liste/lecture des ressources des applications MCP et rendu UI en ligne lorsque pris en charge |
+
+Lorsque le client ne demande aucune portée explicite, l'application accorde les trois afin que le connecteur se comporte comme le flux Connect autorisé par le navigateur. Conservez la page de connexion du jeton de porteur et la solution de secours `npx @agent-native/core@latest connect --token <token>` pour les développeurs locaux, les hôtes de secours et les clients pour lesquels vous avez besoin d'un bloc de configuration prêt à coller.
+
+## Niveaux du catalogue {#catalog-tiers}
+
+Voici l'explication canonique des niveaux du catalogue MCP – d'autres pages sont liées ici.
+
+Le serveur MCP propose par défaut un **catalogue compact à chaque appelant** : connecteurs hébergés (ChatGPT, Claude), clients de code (Claude Code, Cursor, Codex) et proxy local CLI/stdio. La surface d'action complète n'est servie que sur adhésion explicite. Le catalogue n'est jamais déduit du nom du client ou de l'agent utilisateur.
+
+```an-diagram title="Two catalog tiers" summary="Every caller gets the compact tier by default; the full ~105-tool surface is opt-in only. tool-search bridges the gap so nothing is ever truly hidden."
+{
+  "html": "<div class=\"xa-tiers\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">Compact / connector tier &middot; default</span><strong>~20&ndash;30 tools</strong><small class=\"diagram-muted\">Template-declared app actions + cross-app builtins (<code>list_apps</code>, <code>open_app</code>, <code>ask_app</code>, <code>create_embed_session</code>) + always-present <code>tool-search</code>.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Full tier &middot; opt-in</span><strong>~105 tools</strong><small class=\"diagram-muted\">Explicit opt-in only: <code>--full-catalog</code> token or <code>AGENT_NATIVE_MCP_FULL_CATALOG=1</code>.</small></div></div><p class=\"diagram-muted note\"><code>tool-search</code> reaches any full-tier tool on demand &mdash; so the compact default keeps context small without hiding capability.</p>",
+  "css": ".xa-tiers{display:flex;align-items:stretch;gap:14px;flex-wrap:wrap}.xa-tiers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;flex:1;min-width:240px}.xa-tiers .diagram-arrow{align-self:center;font-size:24px;line-height:1}.xa-tiers .note{flex-basis:100%;margin:4px 0 0;font-size:.85em}.xa-tiers code{font-size:.85em}"
+}
+```
+
+### Niveau Compact/Connecteur (par défaut) {#connector-tier}
+
+Par défaut, chaque agent connecté voit un petit catalogue organisé (environ 20 à 30 outils contre environ 105 dans la surface complète) :
+
+- **Application déclarée par modèle actions** — la liste verte sécurisée au niveau de l'application. Pour les plans `create-visual-plan`, `get-visual-plan`, `share-resource`, `navigate`, `tool-search` et similaires.
+- **Outils multi-applications intégrés** : `list_apps`, `open_app`, `ask_app`, `create_embed_session`.
+- **`tool-search`** est toujours présent, donc tout ce qui se trouve en dehors de la liste reste accessible à la demande (voir ci-dessous).
+
+Les outils en dehors de la liste (par exemple `db-exec`, `seed-*`, la suite d'extensions, les outils de session de navigateur et les outils de radiographie contextuelle) ne sont pas annoncés et les appels vers ces outils sont rejetés avec « Outil inconnu », sauf si l'appelant a choisi d'accéder au catalogue complet. Cela permet de garder la fenêtre contextuelle de chaque agent connecté petite et de supprimer les armes à pied qui ne sont sûres que pour le développement local à locataire unique. Le niveau de connecteur est actif **chaque fois qu'un modèle déclare un `connectorCatalog`** — il n'est pas protégé par une variable d'environnement.
+
+`tool-search` fonctionne de deux manières : appelez-le avec **aucune requête** pour le menu complet des noms d'outils ainsi que des descriptions sur une ligne (bon marché, sans schémas), ou avec une requête pour les correspondances classées avec des résumés de paramètres. C'est ainsi qu'un client compact découvre et charge n'importe quel outil pleine surface lorsqu'il en a besoin.
+
+### Niveau complet (adhésion explicite uniquement) {#full-tier}
+
+La surface d'action complète d'environ 105 outils est diffusée uniquement sur inscription explicite, de deux manières :
+
+- **Par jeton** – créé avec `--full-catalog`, qui intègre une revendication `catalog_scope: "full"` dans le JWT. Les requêtes suivantes contournent le filtre compact pour ce jeton :
+
+  ```bash
+  npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
+  ```
+
+- **Par déploiement** : définissez `AGENT_NATIVE_MCP_FULL_CATALOG=1` (environnement du processus serveur) pour qu'il serve la surface complète à tous les appelants. Utilisez-le pour les instances hébergées à locataire unique qui souhaitent bénéficier de la totalité de la surface sans option d'activation par jeton.
+
+### Déclaration de modèle {#catalog-declaration}
+
+Les modèles déclarent leur catalogue de connecteurs dans les options `createAgentChatPlugin` :
+
+```ts
+export default createAgentChatPlugin({
+  appId: "plan",
+  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  connectorCatalog: [
+    "create-visual-plan",
+    "get-visual-plan",
+    "list-visual-plans",
+    "update-visual-plan",
+    // … other safe app-level actions
+    "set-resource-visibility",
+    "share-resource",
+    "upload-image",
+    "navigate",
+    "view-screen",
+    "manage-automations",
+    "tool-search",
+  ],
+});
+```
+
+Les outils multi-applications intégrés (`list_apps`, `open_app`, `ask_app`,
+`create_embed_session`, `create_workspace_app`, `list_templates`) sont toujours
+inclus quelle que soit la liste déclarée.
+
+## Ce que vous pouvez faire une fois connecté {#what-you-can-do}
+
+Une fois votre agent connecté, chaque appelant reçoit le catalogue compact par défaut
+(voir [Catalog tiers](#catalog-tiers)) — clients développeurs code/stdio, le local
+Proxy CLI et hôtes de discussion comme Claude et ChatGPT. Cette surface est la
+application déclarée par modèle actions plus les verbes inter-applications intégrés (`list_apps`,
+`open_app`, `ask_app` et l'assistant d'intégration réservé aux applications). Utilisez `ask_app` pour acheminer un
+tâche en langage naturel via un agent d'application (le même point d'entrée entre applications
+[A2A](/docs/a2a-protocol) utilise). `tool-search` est toujours présent, donc n'importe quel outil
+en dehors de la liste compacte reste accessible à la demande. Pour obtenir l'outil ~105 complet
+faites surface dès le départ, inscrivez-vous explicitement avec `--full-catalog` ou
+`AGENT_NATIVE_MCP_FULL_CATALOG=1`. Dans tous les cas, demandez à l'agent de faire un vrai travail
+et il renvoie un lien directement vers l'application en cours d'exécution :
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…")
+→ Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=…
+```
+
+Cliquez sur ce lien et Mail s'ouvre avec le brouillon restauré, centré exactement là où vous, l'utilisateur connecté, vous trouvez. L'agent n'a jamais eu besoin de connaître votre session ; il vient de produire l'artefact.
+
+### Compatibilité des applications MCP {#mcp-apps-compatibility}
+
+Les applications natives d'agent parlent également l'extension officielle des applications MCP. Quand une action
+déclare `mcpApp`, le serveur annonce
+`extensions["io.modelcontextprotocol/ui"]`, inclut `_meta.ui.resourceUri` /
+`_meta["ui/resourceUri"]` dans `tools/list` et dessert le HTML UI via
+`resources/list` + `resources/read` comme `text/html;profile=mcp-app`. Ressource
+les métadonnées de sécurité telles que CSP et les autorisations sandbox se trouvent sur la ressource
+entrées et contenu `resources/read`, pas sur le descripteur d'outil.
+
+Pour les hôtes d'application OAuth de style ChatGPT/Claude, la surface de découverte est compacte par défaut : `tools/list` et `resources/list` annoncent le chemin d'intégration générique `open_app` au lieu de chaque ressource d'application MCP spécifique à une action (voir [Catalog tiers](#catalog-tiers)). Marquez une action individuelle avec `mcpApp.compactCatalog: true` uniquement lorsqu'elle doit réellement rester visible dans la découverte de l'hôte de discussion.
+
+Cela rend la même surface d'application disponible pour chaque hôte compatible plutôt que de créer des cales par client. Quels hôtes restituent les applications MCP en ligne (et le cache du connecteur se déclenche après les modifications des métadonnées) se trouvent dans [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) – cette page est l'accueil unique de la matrice client.
+
+En pratique, chaque application native d'agent doit être créée avec les deux : applications MCP pour la révision/modification en ligne sur des hôtes compatibles, et `link` pour un aller-retour universel vers l'application complète. Les clients CLI/code-editor qui n’affichent pas d’iframe reviennent au lien profond. Les outils de sélection humaine peuvent ajouter une étape de collage à cette solution de secours : par exemple, le sélecteur d'actifs s'ouvre à partir du lien de secours, permet à l'utilisateur de choisir un média dans le navigateur, puis copie un résumé de transfert que l'utilisateur recolle dans le chat.
+
+### Pont d'application MCP de première classe {#mcp-app-bridge}
+
+`embedApp()` démarre à partir de la cible `link` de l'action, crée une session d'intégration de courte durée et lance cette route d'application signée. Le Web Claude utilise un chemin de transplantation à image unique ; ChatGPT obtient une iframe de route contrôlée avec l'hôte `window.openai` API. Tous les chemins affichent l'itinéraire normal React. Les itinéraires directement hydratés appellent `ui/update-model-context`, `ui/message`, `ui/open-link` et `ui/request-display-mode` via le pont hôte ; le chemin ChatGPT relaie les mêmes requêtes sur le postMessage `agentNative.mcpHost.*`. `embedApp({ height })` est par défaut `560px` et se fixe sur `320-900px`.
+
+Voir [MCP Apps](/docs/mcp-apps) pour plus de détails sur le pont : transplantation ou cadre contrôlé, modes d'intégration, tables `ui/*` et postMessage, règles `embedStartUrl`, CSP, intégration d'extension `srcDoc`, serrage de hauteur et client de pont hôte complet API.
+
+### Verbes génériques inter-applications {#cross-app}
+
+En plus des outils par action, le serveur MCP expose un ensemble de verbes stable, de sorte qu'un agent externe dispose d'une surface prévisible sans deviner les noms d'action par application :
+
+| Outil                                              | Effets secondaires | Retours                                                                                                                              |
+| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `list_apps`                                        | aucun              | applications d'espace de travail + leurs URL/état d'exécution                                                                        |
+| `open_app({ app, view?, path?, params?, embed? })` | aucun              | un lien profond ou une route de même origine ; `embed: true` restitue l'application complète en ligne là où elle est prise en charge |
+| `ask_app({ app, message })`                        | boucle d'agent     | achemine une tâche en langage naturel vers l'agent intégré à l'application (délégués à `ask-agent`)                                  |
+| `create_workspace_app({ name, template })`         | échafaudages       | une nouvelle application démarrée via le chemin de l'espace de travail, ainsi que son URL en cours d'exécution + son lien profond    |
+| `list_templates`                                   | aucun              | les modèles autorisés uniquement                                                                                                     |
+
+`create_workspace_app` rejette tout modèle non autorisé : la liste verte de modèles publics dans `packages/shared-app-config/templates.ts` fait autorité et est protégée par CI ; un agent extérieur ne peut pas l’élargir. Une action de modèle du même nom remplace une action intégrée (précédence du modèle sur le noyau). Désactivez l'ensemble avec `MCPConfig.builtinCrossAppTools: false`.
+
+Les catalogues d'outils et de ressources pour les hôtes d'applications sont compacts par défaut – voir [Catalog tiers](#catalog-tiers). `publicAgent.expose` reste l'option d'adhésion pour les outils de lecture/ingestion sécurisés en dehors de ce catalogue compact ; définissez `mcpApp.compactCatalog: true` uniquement comme une exception rare pour actions qui doit apparaître dans la découverte de l'hôte de discussion.
+
+Pour des transferts rapides ChatGPT/Claude, le chemin idéal est direct : appelez l'action qui crée ou ouvre l'artefact, puis laissez l'application MCP lancer l'itinéraire. Une requête Mail doit appeler `manage_draft` et afficher la véritable route de composition. Une demande de tableau de bord doit appeler `open_app({ path, embed: true })` ou une action de tableau de bord avec `mcpApp` et afficher l'itinéraire Analytics complet. Le calendrier, les formulaires, le contenu, les diapositives, la conception et les clips doivent suivre le même modèle avec leur brouillon/création/recherche actions. `list_apps` est utile lorsque le modèle doit choisir parmi les applications accordées ; Une large `resources/list`, une découverte de catalogue complet ou une délégation `ask_app` ne devraient pas être la voie normale pour un transfert évident de UI.
+
+### Visite par application {#tour}
+
+Chaque modèle sur liste verte qui produit ou répertorie une ressource navigable est livré avec un générateur `link`, et ceux qui sont lourds à ingérer envoient une action GET + `publicAgent` afin qu'un agent connecté puisse extraire l'état en direct :
+
+- **Mail** — `manage-draft` renvoie un lien profond codé en `compose` ; cliquer dessus ouvre la boîte de réception avec le brouillon restauré dans un `compose-<id>`. `list-emails` / `search-emails` pointent vers une vue filtrée de la boîte de réception.
+- **Calendrier** — `manage-event-draft` renvoie un lien profond `calendarDraft` + `eventDraftId` ; cliquer dessus ouvre un brouillon d'espace réservé visible sur le calendrier avec l'éditeur d'événements natif pour révision/envoi. `create-event` renvoie toujours `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` ; le clic atterrit sur le calendrier avec cet événement centré sur sa date.
+- **Analytics** — `update-dashboard` / `save-analysis` renvoie `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })` ; l'agent crée un tableau de bord sur MCP et rend "Ouvrir le tableau de bord dans Analytics".
+- **Design** — `get-design-snapshot` est l'action d'ingestion GET + `publicAgent` : elle renvoie le contenu du fichier Yjs **live** ainsi que les valeurs de réglage résolues afin que l'agent continue à partir de la conception optimisée, et non des jetons d'origine. `apply-tweaks` fait un aller-retour avec un lien vers l'éditeur "Ouvrir la conception".
+- **Contenu** — `pull-document` est l'action d'ingestion GET + `publicAgent` : elle vide d'abord toute session collaborative en direct ouverte vers SQL afin que l'agent externe ingère exactement ce que l'utilisateur voit, puis fait apparaître un lien profond vers le document.
+- **Brain** — `ask-brain` / `search-everything` renvoie une réponse citée ainsi qu'un lien profond vers la connaissance/capture sous-jacente, de sorte que la recherche d'un agent de terminal renvoie directement à la source dans l'application en cours d'exécution.
+
+## Création (pour les auteurs de modèles) {#authoring}
+
+Tout ce qui précède est destiné aux **utilisateurs finaux** qui se connectent et utilisent une application. Le reste de cette page est destiné aux **auteurs de modèles** qui préparent une application pour qu'elle devienne un bon citoyen d'agent externe : le générateur `link`, les applications MCP facultatives UI, les composants internes de la route `/_agent-native/open` et l'ingestion de actions.
+
+### Le constructeur `link` {#link-builder}
+
+`defineAction` accepte un générateur `link` en option. Lorsqu'il est défini, chaque résultat MCP/A2A pour cet outil ajoute automatiquement un bloc de markdown `[label →](absoluteUrl)` et un `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }` structuré. `tools/list` ajoute `annotations["agent-native/producesOpenLink"]` et un suffixe de description afin que l'agent externe sache que l'outil génère un lien ouvrable et doit le faire apparaître.
+
+Construisez le URL avec le `buildDeepLink(...)` : il s'agit de la source unique de vérité pour le format open-route. Ne formatez jamais manuellement le `/_agent-native/open` URL.
+
+Exemple réel : `manage-draft` (`templates/mail/actions/manage-draft.ts`) du courrier :
+
+```ts
+import { buildDeepLink } from "@agent-native/core/server";
+
+function composeDeepLink(draft: Record<string, string>): string {
+  return buildDeepLink({
+    app: "mail",
+    view: "inbox",
+    compose: encodeComposeDraft(draft), // base64url JSON → compose-<id> draft
+  });
+}
+
+export default defineAction({
+  // ...schema, run...
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const draft = (result as { draft?: Record<string, string> }).draft;
+    const id = (result as { id?: string }).id;
+    if (!draft || !id) return null;
+    return {
+      url: composeDeepLink(draft),
+      label: "Open draft in Mail",
+      view: "inbox",
+    };
+  },
+});
+```
+
+Liste/recherche actions pointe vers une vue axée sur les enregistrements de la même manière – par ex. le `create-event` du calendrier renvoie `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` avec l'étiquette `"Open event in Calendar"`. Le brouillon de calendrier actions utilise le même modèle : `manage-event-draft` renvoie `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` avec l'étiquette `"Review invite in Calendar"`, afin que les agents externes puissent renvoyer un lien direct de révision du brouillon sans créer d'abord l'événement.
+
+### Applications MCP en option UI {#mcp-apps}
+
+Actions peut annoncer une ressource UI en ligne avec `mcpApp` pour les hôtes prenant en charge l'extension d'applications MCP. Utilisez `embedRoute({ title, openLabel, path })` comme emballage pratique ou attribuez directement `embedApp(...)` à `mcpApp.resource`. Chaque application MCP est un véritable itinéraire React, et non un widget simple HTML distinct. Conservez toujours le générateur `link` : les hôtes CLI uniquement, les clients plus anciens et les hôtes non-MCP-Apps l'utilisent comme solution de secours.
+
+Voir [MCP Apps](/docs/mcp-apps) pour le guide de création complet : `embedRoute` vs `embedApp`, la forme de configuration `mcpApp`, CSP, la hauteur, le chemin d'intégration `sendToAgentChat()` et les assistants client du pont hôte.
+
+### Le contrat `link` {#link-contract}
+
+Le générateur `link` est **pur et synchrone : pas d'E/S, pas d'attente**. Il s'exécute au mieux : un lancer, `null` ou `undefined` est avalé et ne fait **jamais** échouer à l'appel de l'outil. Il lit uniquement les `args` et `result` de l'appel ; il ne doit pas interroger la base de données, lire l'état de l'application ou appeler un autre actions. Renvoyez `null` lorsqu'il n'y a rien à ouvrir.
+
+`buildDeepLink({ app, view, params?, to?, compose? })` renvoie le chemin relatif à l'application `/_agent-native/open?app=…&view=…&<recordId>=…`. La couche MCP transforme cela en un Web absolu URL (`toAbsoluteOpenUrl`, en utilisant l'origine de la requête), un bureau `agentnative://open?…` URL (`toDesktopOpenUrl`) et une extension VS Code URL (`toVsCodeOpenUrl`) pour `vscode://builder.agent-native/open?url=…` ; le lien de démarque utilise le bureau URL lorsque le client signale `target: "desktop"`.
+
+### L'itinéraire `/_agent-native/open` {#open-route}
+
+Lorsque l'utilisateur clique sur le lien dans n'importe quel navigateur ou vue Web en ligne, `GET /_agent-native/open` (`createOpenRouteHandler`, monté par le plug-in de routes principales) exécute les étapes ci-dessous.
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/open",
+  "summary": "Deep-link open route — focuses the browser UI on a record",
+  "description": "Resolves the browser session, writes a one-shot `navigate` application-state command scoped to that session, and 302-redirects to a safe same-origin path. Always build the URL with `buildDeepLink(...)`; never hand-format it. Can be disabled per app with `disableOpenRoute`.",
+  "auth": "Browser session via `getSession`. The auth guard bypasses this exact path; if unauthenticated it serves login HTML at the same URL, and the form reload re-enters authenticated (no `?next=` plumbing).",
+  "params": [
+    { "name": "app", "in": "query", "type": "string", "description": "Target app id (e.g. `mail`)." },
+    { "name": "view", "in": "query", "type": "string", "description": "View to focus; also folded into the `navigate` payload." },
+    { "name": "to", "in": "query", "type": "string", "description": "Optional explicit same-origin relative redirect target. Falls back to `/<view>`, then a per-template `resolveOpenPath`." },
+    { "name": "compose", "in": "query", "type": "string", "description": "base64url-encoded draft, decoded into a `compose-<id>` application-state key." },
+    { "name": "f_*", "in": "query", "type": "string", "description": "Filter params forwarded to the redirect so lists/dashboards open pre-filtered." }
+  ],
+  "responses": [
+    { "status": "302", "description": "Redirect to a safe same-origin relative path. Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard)." },
+    { "status": "200", "description": "Login HTML served at the same URL when the browser session is unauthenticated." }
+  ]
+}
+```
+
+1. Résout la session **navigateur** via `getSession` (le garde d'authentification contourne le chemin exact `/_agent-native/open`).
+2. Si non authentifié, sert la connexion configurée HTML **au même URL** ; le gestionnaire de réussite du formulaire recharge `window.location`, en entrant à nouveau l'itinéraire authentifié — pas de plomberie `?next=`.
+3. Écrit la commande d'état d'application unique `navigate` existante (charge utile = chaque paramètre de requête non réservé + `view`) limitée à l'e-mail de la session de navigateur avec `requestSource: "deep-link"`, et décode un brouillon d'url base64 `compose` en une clé `compose-<id>`.
+4. 302-redirections vers un chemin relatif sûr de même origine (`to=`, sinon `/<view>`, sinon un `resolveOpenPath` par modèle), transmettant les paramètres de filtre `f_*` afin que les listes/tableaux de bord s'ouvrent pré-filtrés avant même que la commande `navigate` ne soit drainée.
+
+Les redirections d'origine croisée, `//host` relatives au schéma et les redirections de caractères de contrôle sont rejetées (garde de redirection ouverte). L'itinéraire peut être désactivé par application via `disableOpenRoute`.
+
+#### La règle d'identité de session de navigateur {#identity-rule}
+
+Le lien ne comporte **aucun état privilégié** — il s'agit simplement de `view` + identifiants d'enregistrement + filtres. L'écriture `navigate` axée sur l'enregistrement s'étend à toute personne connectée au **navigateur**, jamais au jeton MCP de l'agent externe. Ainsi, un agent authentifié sous une seule identité peut remettre un lien à un utilisateur, et lorsque cet utilisateur clique dessus, l'enregistrement s'ouvre là où _l'utilisateur_ est connecté. C'est ce qui permet au lien profond de faire surface en toute sécurité dans un terminal ou une transcription de discussion. Voir [Context Awareness](/docs/context-awareness) pour le contrat `navigate` / `application_state` auquel ce pont fait référence.
+
+### Ingérer actions {#ingest}
+
+Une action lue par un agent externe pour extraire l'état de l'application en direct dans son propre contexte doit être :
+
+```ts
+export default defineAction({
+  description: "…",
+  schema: z.object({ id: z.string() }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ id }) => {
+    /* read LIVE state, not the stale DB snapshot column */
+  },
+});
+```
+
+`GET` + `readOnly` maintient l'action sans effet secondaire et en dehors de l'événement de changement d'actualisation de l'écran. `publicAgent` est l'**opt-in explicite** — un itinéraire Web public n'implique jamais une exposition publique à MCP/A2A ; voir [Actions](/docs/actions). Conception/contenu ingéré actions MUST lit l'état **en direct** (le document collaboratif Yjs, pas la colonne d'instantané de base de données obsolète) afin que l'agent externe voie ce que l'utilisateur a réellement à l'écran. Le `pull-document` de Content transfère d'abord toute session de collaboration en direct ouverte vers SQL ; Le `get-design-snapshot` de Design renvoie le contenu du fichier Yjs en direct ainsi que les valeurs de réglage résolues par l'utilisateur.
+
+## Avancé : développement local et configuration manuelle {#advanced}
+
+Le flux `connect` hébergé ci-dessus est le chemin recommandé. Les options ci-dessous concernent le développement local et les configurations réalisées à la main.
+
+### Développement local {#local-dev}
+
+Exécutez votre application localement (`pnpm dev` / `npx @agent-native/core@latest dev`), puis pointez un agent local dessus avec une seule commande :
+
+```bash
+npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
+
+Il provisionne un jeton (un `ACCESS_TOKEN` aléatoire dans l'espace de travail `.env` pour le développement local, ou un JWT signé s'il détecte une origine hébergée) et écrit une entrée de serveur stdio idempotent :
+
+- **claude-code / claude-code-cli** — une entrée `mcpServers` dans `.mcp.json` (portée du projet, par défaut) ou `~/.claude.json` (`--scope user`).
+- **cowork** — la même forme du code Claude JSON dans `~/.cowork/mcp.json`.
+- **codex** — un bloc `[mcp_servers.<name>]` dans `~/.codex/config.toml`.
+
+L'entrée exécute `npx @agent-native/core@latest mcp serve --app <id>`, qui est par défaut un **thin stdio proxy** pour le `/_agent-native/mcp` de l'application locale en cours d'exécution — de sorte que le registre d'action en direct, HMR et les liens profonds corrects restent la source unique de vérité. Transmettez `--standalone` pour créer le registre en cours de processus. Lorsque `npx @agent-native/core@latest mcp install` détecte une origine hébergée (un hôte non local `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` dans l'espace de travail `.env`), il écrit une entrée client `http` pointant vers `<origin>/_agent-native/mcp` avec un `Bearer` JWT au lieu d'une entrée stdio.
+
+Sous-commandes compagnon :
+
+| Commande                                                   | Ce qu'il fait                                                                         |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `npx @agent-native/core@latest mcp serve [--app <id>]`     | Exécutez le transport stdio MCP (quelles configurations client génèrent).             |
+| `npx @agent-native/core@latest mcp install --client <c>`   | Provisionner un jeton + écrire la configuration MCP du client (idempotent).           |
+| `npx @agent-native/core@latest mcp uninstall --client <c>` | Supprimez l'entrée nommée MCP de la configuration d'un client (idempotent).           |
+| `npx @agent-native/core@latest mcp status`                 | Afficher le MCP URL résolu/port, l'état du jeton et les entrées par client.           |
+| `npx @agent-native/core@latest mcp token [--rotate]`       | Imprimez (ou faites pivoter) le `ACCESS_TOKEN` local dans l'espace de travail `.env`. |
+
+Redémarrez le client après `install` pour qu'il récupère le nouveau serveur MCP.
+
+### Saisie manuelle `.mcp.json` HTTP {#manual-entry}
+
+Vous pouvez également écrire manuellement la configuration du client MCP sur n'importe quel point de terminaison déployé avec un jeton que vous fournissez vous-même (un `ACCESS_TOKEN` ou un JWT signé par `A2A_SECRET` portant le `sub` + `org_domain` de l'appelant afin que l'exécution de l'outil reste à l'échelle du locataire) :
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+C'est l'équivalent non géré de ce que `connect` écrit pour vous. Voir [MCP Protocol](/docs/mcp-protocol) pour la matrice d'authentification complète env-var.
+
+### Surface des outils de développement et de production {#dev-vs-prod}
+
+Dans le développement local simple (`NODE_ENV=development` et `AGENT_MODE !== "production"`), le MCP `tools/list` expose délibérément uniquement les éléments génériques intégrés plus actions avec `publicAgent.requiresAuth === false` — l'ingestion par application actions (`requiresAuth: true`) et la mutation actions (pas de `publicAgent`) sont filtrées. (`filterPublicAgentActions`). Le catalogue compact est la valeur par défaut pour chaque appelant après l'authentification - les clients stdio/code utilisant le proxy `agent-native`, le CLI local et les appelants distants HTTP de type chat - donc ChatGPT/Claude (ou n'importe quel client) ne peut pas transférer un énorme catalogue d'actions complet dans la conversation. Le catalogue complet des développeurs est servi uniquement sur adhésion explicite (jeton `--full-catalog` ou `AGENT_NATIVE_MCP_FULL_CATALOG=1`) ; Le `tool-search` permet de garder tous les outils accessibles entre-temps.
+
+### Basculer les applications propriétaires entre la production et le développement {#dev-switch}
+
+Lorsque vous disposez déjà d'applications hébergées propriétaires connectées et que vous souhaitez tester les modifications du framework local via `pnpm dev:lazy`, utilisez le sélecteur de développeur :
+
+```bash
+pnpm dev:lazy -- --apps mail,calendar,analytics
+
+npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
+```
+
+`connect dev` réécrit les mêmes noms de serveur MCP stables (`agent-native-mail`, `agent-native-calendar`, etc.) sur la passerelle de développement paresseux locale, de sorte que les noms des outils ne changent pas. Il sauvegarde les entrées de production actuelles dans `~/.agent-native/connect-profiles.json` avant d'écrire les entrées de développement. La passerelle par défaut est `http://127.0.0.1:8080` ; utilisez `--gateway <url>` ou `--port <n>` si votre passerelle a déménagé.
+
+Revenir en arrière avec :
+
+```bash
+npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
+```
+
+Si `connect dev` ne peut pas déduire votre identité de propriétaire local à partir d'un JWT connecté existant, transmettez `--owner-email you@example.com` ; cela conserve les outils de développement locaux sur la surface MCP entièrement authentifiée au lieu de la surface de développement clairsemée non authentifiée.
+
+## Fonctionnement et sécurité {#how-it-works}
+
+Le chemin OAuth standard n'expose jamais les jetons aux applications MCP : l'hôte stocke les jetons d'accès/actualisation OAuth et assure la médiation des appels d'outils et `resources/read` via la connexion authentifiée MCP. Les iframes intégrées reçoivent les données de l'application et les résultats des outils, pas les secrets du porteur.
+
+Les intégrations d'applications complètes évitent également de transmettre le jeton du porteur MCP au navigateur. L'appelant MCP génère un ticket d'intégration unique dans SQL ; la route de lancement de l'iframe le consomme et définit un cookie de session de navigateur de courte durée et sécurisé par l'iframe. L'atterrissage URL contient un paramètre de requête `__an_embed_token` temporaire juste assez longtemps pour que le client puisse le capturer, le supprimer de la barre d'adresse et l'attacher aux appels `fetch` de même origine lorsque les cookies tiers sont bloqués. Les sessions d'intégration sont limitées à l'itinéraire ; les récupérations d'application incluent la cible intégrée actuelle et le serveur rejette la réutilisation du jeton en dehors de la route créée. Les pages d'application n'émettent intentionnellement pas `X-Frame-Options` ou CSP `frame-ancestors`, de sorte que les hôtes d'application Builder, Design et MCP peuvent les iframer. Les navigations iframe du navigateur optent également pour COEP/CORP lorsque cela est nécessaire pour les hôtes isolés d'origines croisées.
+
+Le flux `connect` hébergé de secours ne copie jamais le secret partagé du déploiement. Au lieu de cela :
+
+- Une session de navigateur connectée génère un jeton **par utilisateur, limité et révocable** : un JWT signé `A2A_SECRET` portant le `sub` + `org_domain` de l'appelant et un `jti` unique, de sorte que chaque exécution d'outil reste limitée au client via `runWithRequestContext`.
+- Le point de terminaison `/_agent-native/mcp` existant accepte ce jeton comme n'importe quel autre support (voir [MCP Protocol](/docs/mcp-protocol)) — pas de nouveau point de terminaison, pas de nouveau transport.
+- La même page Connect répertorie tous les jetons que vous avez créés et vous permet de **révoquer** n'importe lequel d'entre eux par `jti`. Traitez-les comme des jetons d'accès personnels : un par client agent, révoqué lorsqu'une machine est mise hors service.
+- Le lien profond que l'agent restitue ne comporte aucun état privilégié. L'écriture `navigate` axée sur l'enregistrement est toujours limitée à la session du **navigateur**, jamais au jeton de l'agent. Un lien peut donc être collé en toute sécurité dans un terminal ou une transcription de discussion.
+
+## Faire/Ne pas faire {#do-dont}
+
+**Faire**
+
+- Connectez votre propre agent à Dispatch avec `npx @agent-native/core@latest connect https://dispatch.agent-native.com` ; utilisez une application directe URL uniquement lorsque vous souhaitez une application isolée.
+- Ajoutez un générateur `link` à toute action qui produit ou répertorie une ressource navigable (brouillon, événement, tableau de bord, document).
+- Construisez le URL avec `buildDeepLink(...)` – la source unique de vérité pour le format open-route.
+- Gardez `link` pur et synchrone ; renvoie `null` lorsqu'il n'y a rien à ouvrir.
+- Faites en sorte que l'agent externe ingère actions GET + `readOnly` + `publicAgent` et lise l'état en direct (Yjs), pas la colonne de base de données obsolète.
+- Laissez la route ouverte résoudre la session du navigateur ; transmettez les identifiants d'enregistrement en tant que paramètres de lien profond et laissez le UI les concentrer via la commande `navigate` interrogée.
+- Révoquer un jeton de connexion créé par `jti` lorsqu'un client agent est mis hors service.
+- Testez les applications MCP avec les appareils légers autour de `embedApp()` et
+  `McpAppRenderer` ; ils couvrent CSP, le contexte de l'hôte, le lancement de l'application et le pont
+  comportement des messages sans avoir besoin d'un véritable hôte externe.
+- Lors de la validation du Web ChatGPT ou Claude, déclenchez un nouvel appel d'outil après le shell
+  modifie et mesure l'iframe visible. Images précédemment rendues dans le
+  la même conversation peut toujours afficher la hauteur en cache ou le comportement de lancement.
+- Gardez les catalogues d'hôtes d'application ChatGPT/Claude compacts. Utilisez Dispatch et
+  `open_app({ embed: true })` pour les aperçus complets de l'application ; marquez uniquement un spécifique
+  action `mcpApp.compactCatalog: true` lorsqu'elle doit apparaître directement dans le
+  Surface de découverte d'hôtes compacte.
+
+**Ne pas faire**
+
+- Copiez le `ACCESS_TOKEN` / `A2A_SECRET` partagé d'un déploiement dans une configuration client lorsque `connect` peut créer un jeton révocable par utilisateur à la place.
+- Formatez manuellement le `/_agent-native/open` URL — passez toujours par `buildDeepLink`.
+- Effectuer des E/S, des attentes, des lectures de base de données ou des lectures d'état d'application dans un générateur `link`.
+- Étendez l'écriture `navigate` sur le jeton d'agent ou transmettez l'état privilégié via le lien profond : il s'agit d'un pur pointeur.
+- Inventer un nouveau mécanisme de navigation ; pont vers le contrat `navigate` / `application_state` existant.
+- Élargissez la liste verte des modèles publics lors de la création d'une application à partir d'un agent externe : la liste verte fait autorité et est protégée.
+
+## Connexe {#related}
+
+- [MCP Apps](/docs/mcp-apps) : création de l'application MCP UI, du pont intégré et du pont hôte API.
+- [MCP Protocol](/docs/mcp-protocol) : le serveur MCP monté automatiquement et le méta-outil `ask-agent`.
+- [MCP Clients](/docs/mcp-clients) — la direction symétrique : votre application consomme des serveurs MCP locaux/distants.
+- [A2A Protocol](/docs/a2a-protocol) : le méta-outil `ask-agent` et les appels homologues JSON-RPC.
+- [Actions](/docs/actions) — définissant actions, `publicAgent`, GET / `readOnly`.
+- [Context Awareness](/docs/context-awareness) — les `navigate` / `application_state` contractent les ponts à route ouverte.