---
title: Connecter un client IA (MCP)
description: Connectez Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT ou les SDK OpenAI à l'endpoint MCP admin de votre panel.
url: https://nexcmp.com/fr/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Connecter un client IA (MCP) {#connect-an-ai-client-mcp}

> **Où dans l'admin :** System › Settings › API & AI agents (`/agent/keys`), l'onglet **Connect an AI** affiche l'URL de l'endpoint et un extrait prêt à copier pour chaque client, complété avec la clé que vous venez de créer.

## Description {#what-it-does}

Le protocole **Model Context Protocol (MCP)** permet à un client IA d'appeler des outils. Votre panel héberge un serveur MCP administrateur sur `https://cloud.example.com/mcp/admin`. Connectez votre propre outil IA et demandez en langage naturel : "what is left to set up?", "add my Proxmox cluster", "create plans with a 40% margin". Le client appelle les outils administrateur ci-dessous ; le panel vérifie les portées, vous demande confirmation avant toute action risquée et enregistre chaque appel.

::: info Deux endpoints MCP
`/mcp` est l'endpoint **client** (clés API client, `vk_` ; voir [MCP server](https://nexcmp.com/fr/docs/developers/mcp/)). `/mcp/admin` est l'endpoint **admin** décrit ici (clés admin `ak_` ou OAuth). Les deux ne se mélangent jamais : les outils admin ne sont pas visibles sur `/mcp`, et `/mcp/admin` n'accepte que les clés admin.
:::

## Prérequis {#requirements}

| Élément | Prérequis |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` sur le propre domaine de votre panel. Copiez l'URL exacte depuis l'onglet **Connect an AI**. La même page liste une URL locale (`http://127.0.0.1:<port>/mcp/admin`) pour les outils s'exécutant directement sur le serveur. |
| Identifiants | Une [clé API admin](https://nexcmp.com/fr/docs/configure-with-ai/admin-api-keys/) (`ak_...`) avec les portées souhaitées, **ou** une connexion OAuth pour les connecteurs web ([OAuth connectors](https://nexcmp.com/fr/docs/configure-with-ai/oauth-connectors/)). |
| Client | Tout client MCP compatible avec le transport **Streamable HTTP** et un en-tête personnalisé `Authorization`. Versions du protocole 2025-11-25, 2025-06-18 et 2025-03-26. |
| Réseau | Si vous placez votre propre proxy inverse devant le panel, il doit transmettre `/mcp/admin`. Les connecteurs web (claude.ai, ChatGPT) se connectent depuis les serveurs du fournisseur, l'URL doit donc être accessible depuis Internet. |

## Préparer l'infrastructure {#prepare-the-infrastructure}

Rien à installer sur le serveur. Si vous restreignez la clé par IP, assurez-vous que l'adresse depuis laquelle votre client se connecte se trouve dans la plage. Testez d'abord l'accessibilité :

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

Une réponse `401` avec un en-tête `WWW-Authenticate: Bearer ... resource_metadata=...` indique que l'endpoint est actif et attend des identifiants.

## Connecter dans NexCMP {#connect-in-nexcmp}

1. Créer une clé : **System › Settings › API & AI agents › API keys › New key**. Pour un premier essai, utilisez uniquement `admin:read` ; ajoutez des portées d'écriture lorsque vous en avez besoin. Voir [Admin API keys](https://nexcmp.com/fr/docs/configure-with-ai/admin-api-keys/).
2. Ouvrez l'onglet **Connect an AI**. Tant que la boîte de dialogue de création de clé est active, chaque extrait ci-dessous contient déjà votre vraie clé. Sinon, elle affiche le paramètre fictif `ak_YOUR_KEY`.
3. Copiez l'extrait correspondant à votre client et exécutez-le ou collez-le comme décrit ci-dessous.

![Onglet Connect an AI affichant l'URL MCP et une carte avec un bouton de copie par client](https://nexcmp.com/fr/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

Lancez ensuite `claude` et demandez "list the tools from nexcmp" ou "what is left to set up?".

Vérifié le 30/10/2026 avec Claude Code 2.1 : `claude mcp add --transport http …` enregistre le serveur (ajoutez `-s project` pour le conserver dans le fichier `.mcp.json` du projet — Claude Code vous demande d'approuver les serveurs de projet la première fois). Pour les scripts, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` s'exécute sans invite d'approbation et permet à Claude d'utiliser uniquement les outils du panel.

### Claude Desktop {#claude-desktop}

Requiert Node.js 18 ou une version ultérieure. Ajoutez ceci à `claude_desktop_config.json` (le pont `mcp-remote` est utilisé) et redémarrez Claude Desktop :

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

Si votre système corrompt l'espace dans l'argument d'en-tête, placez plutôt la valeur entière dans une variable d'environnement, exactement comme pour l'endpoint client : `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` avec `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (connecteur personnalisé) {#claude-ai-custom-connector}

Aucune clé requise : la connexion s'effectue via OAuth. Dans claude.ai, ouvrez les paramètres des connecteurs, ajoutez un connecteur personnalisé, collez `https://cloud.example.com/mcp/admin`, puis connectez-vous avec votre compte administrateur NexCMP et sélectionnez les autorisations sur l'écran de consentement. Détails : [OAuth connectors](https://nexcmp.com/fr/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (mode développeur) {#chatgpt-developer-mode}

Aucune clé requise. Dans ChatGPT, activez le mode développeur, ajoutez un connecteur MCP avec l'URL `https://cloud.example.com/mcp/admin`, choisissez OAuth et connectez-vous avec votre compte administrateur NexCMP. Détails : [OAuth connectors](https://nexcmp.com/fr/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Ajouter à `~/.codex/config.toml` :

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

Exportez ensuite la clé dans le shell qui lance Codex :

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip Non-interactive `codex exec`
Dans `codex exec` (scripts, CI), Codex ne demande pas confirmation avant d'appeler des outils et ignore ceux qui modifient des données. Ajoutez `default_tools_approval_mode = "approve"` sous `[mcp_servers.nexcmp]` pour l'autoriser à les appeler ; le panneau renvoie toujours un aperçu et demande confirmation pour les actions financières, de sécurité et de suppression. Vérifié avec Codex CLI 0.166 le 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Ajouter à `~/.gemini/settings.json` :

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI désactive les serveurs MCP dans les dossiers qu'il n'approuve pas. Lancez-le dans un dossier de confiance (ou approuvez le dossier lorsqu'il le demande), puis vérifiez avec `gemini mcp list` — cela affiche `nexcmp … Connected`. Vous pouvez garder la clé hors du fichier avec `"Authorization": "Bearer $NEXCMP_KEY"`. Vérifié avec Gemini CLI 0.66 le 30/10/2026.

### Cursor {#cursor}

Ajouter à `~/.cursor/mcp.json` (ou `.cursor/mcp.json` dans un projet) :

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip Conserver la clé hors des fichiers de configuration
Lorsque le client le prend en charge, lisez la clé à partir d'une variable d'environnement au lieu de l'écrire dans le fichier : Codex le fait par défaut (`bearer_token_env_var`) et Cursor accepte `"Bearer ${env:NEXCMP_KEY}"`. Ne commitez jamais un fichier contenant une clé.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

Une exécution complète (vérifiée avec `openai-agents` 0.24 le 30/10/2026 — un outil de lecture, puis un changement de solde qui a renvoyé l'aperçu de confirmation et a été appliqué au second appel avec `confirm_token`) :

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

Passez le serveur en tant qu'outil de type `mcp`. Gardez `require_approval` sur `always` pour que votre programme vous demande confirmation avant chaque appel :

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### Tout le reste (HTTP non sécurisé) {#anything-else-plain-http}

Un client sans MCP peut appeler les mêmes outils via HTTP. `GET /v1/admin/agent/tools` les liste, `POST /v1/admin/agent/tools/<name>` en exécute un avec un corps JSON d'arguments et `GET /v1/admin/openapi.json` renvoie une description OpenAPI 3.1 (chaque outil correspond à une opération). Tous nécessitent `Authorization: Bearer ak_...`.

## Vérification {#verify}

1. Sans client, lister les outils :

   ```bash
   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_XXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   ```

   La réponse est un résultat JSON-RPC contenant les outils autorisés par vos portées (scopes).
2. Dans votre client, demandez « run system_health ». Il renvoie les alertes, l'état de santé de l'infrastructure connectée, les paiements, l'e-mail, l'IA et l'état de la licence.
3. Ouvrez **API & AI agents › Activity**: les appels sont listés avec le nom du client et `mcp`.
4. Sur le serveur, `sudo nexcmp status` affiche une ligne « MCP admin » indiquant `ready` lorsque l'endpoint répond (un code HTTP 401 sans clé correspond à l'état sain).

## Outils {#tools}

Le serveur propose 58 outils. Un client ne voit que les outils autorisés par les portées (scopes) de sa clé : les outils de lecture nécessitent `admin:read`, les outils d'écriture requièrent leur propre portée. Les outils d'écriture acceptent également un argument optionnel `confirm_token` (voir [Confirmation](#confirmation-confirm-token)). Les arguments sont vérifiés par rapport au schéma de chaque outil : les arguments inconnus ou mal saisis sont rejetés avec un message indiquant leur nom.

Les prix sont en USD : prix des plans en dollars par heure (`hourly_usd`), soldes en centimes. Les secrets peuvent être définis mais ne sont jamais renvoyés.

### Overview and logs {#overview-and-logs}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `system_health` | Alertes nécessitant une attention, état de santé de l'infrastructure, paiements, e-mail, IA, licence et statut des mises à jour. | `admin:read` | No | No |
| `setup_checklist` | Ce qui est configuré et ce qui reste : licence, infrastructure, zone, modèles d'OS, plans, paiements, e-mail, image de marque, mentions légales, commande de test. | `admin:read` | No | No |
| `license_status` | Statut de la licence et présence éventuelle d'une version de NexCMP plus récente. | `admin:read` | No | No |
| `audit_search` | Rechercher dans le journal d'audit administrateur et le journal des clés API. | `admin:read` | No | No |

### Paramètres, image de marque, mentions légales, modules {#settings-branding-legal-modules}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `settings_get` | Lire les paramètres généraux (`keys` filtres ; un `*` final correspond à un préfixe). | `admin:read` | No | No |
| `settings_update` | Modifier les paramètres généraux à partir d'un objet `values` plat. Seules les clés listées par `settings_get` sont acceptées. | `settings:write` | Oui | Lorsqu'une clé touche aux paiements, à la sécurité des connexions, aux commutateurs globaux ou aux prix |
| `branding_get` | Nom de marque, couleur, devise d'affichage, nom du vendeur, URLs du logo et du favicon. | `admin:read` | No | No |
| `branding_update` | Définir le nom de marque (jusqu'à 60 caractères), la couleur (`#rrggbb`), la devise d'affichage (`usd` ou `vnd`) et le nom du vendeur. | `settings:write` | Oui | No |
| `branding_logo_set` | Téléchargez un logo clair ou sombre ou un favicon depuis une URL https ou en base64 (PNG, JPEG, WEBP, ICO ou SVG, jusqu'à 512 Ko). | `settings:write` | Oui | No |
| `legal_get` | Conditions d'utilisation et politique de confidentialité (en anglais et en vietnamien) ainsi que les valeurs neutres par défaut. | `admin:read` | No | No |
| `legal_update` | Définissez le texte des conditions et de la politique de confidentialité (markdown simple, sans HTML, jusqu'à 50 Ko chacun). Une chaîne vide rétablit la valeur par défaut. | `settings:write` | Oui | No |
| `modules_get` | Quels modules optionnels sont activés et lesquels peuvent être commutés. | `admin:read` | No | No |
| `module_set` | Activez ou désactivez un module optionnel (`key` doit être l'un des éléments suivants : `settable`). | `settings:write` | Oui | No |

### E-mail et alertes {#email-and-alerts}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `smtp_get` | Paramètres des e-mails sortants (mot de passe masqué) et état de la file d'attente. | `admin:read` | No | No |
| `smtp_configure` | Définissez le serveur SMTP. Toute modification de l'hôte, du port ou de la sécurité nécessite à nouveau le mot de passe. | `settings:write` (+ `secrets:write` pour le mot de passe) | Oui | No |
| `smtp_test` | Envoyez un véritable e-mail de test avec les paramètres enregistrés. | `settings:write` | Envoie un e-mail | No |
| `telegram_get` | Canaux de notification pour les administrateurs (identifiants de chat ; les jetons de bot ne sont jamais renvoyés). | `admin:read` | No | No |
| `telegram_configure` | Ajoutez ou mettez à jour le canal d'alerte Telegram (jeton de bot et identifiant de chat) et activez ou désactivez les alertes administrateur. | `settings:write` (+ `secrets:write` pour le jeton) | Oui | No |
| `telegram_test` | Envoyez un message de test sur le canal Telegram. | `settings:write` | Envoie un message | No |

### Paiements et devise {#payments-and-currency}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `payments_get` | Statut de Stripe, PayPal, des cryptomonnaies (USDT) et du virement bancaire, ainsi que des canaux activés et des frais. | `admin:read` | No | No |
| `payment_configure` | Définissez les identifiants d'une passerelle (`stripe`, `paypal`, `crypto` ou `bank`). | `billing:write` (+ `secrets:write`) | Oui | Toujours |
| `payment_test` | Vérifiez les identifiants enregistrés d'une passerelle auprès du fournisseur. | `billing:write` | No | No |
| `currency_get` | Devise d'affichage et taux USD vers VND (automatique ou manuel). | `admin:read` | No | No |
| `currency_set` | Définissez la devise d'affichage et/ou un taux manuel (0 signifie automatique, sinon de 15000 à 50000). | `billing:write` | Oui | Lorsque vous modifiez le taux manuel |

### Infrastructure et zones {#infrastructure-and-zones}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `cloudstack_get` | Point de terminaison CloudStack, zone et identifiants réseau enregistrés (clés masquées). | `admin:read` | No | No |
| `cloudstack_test` | Testez un point de terminaison avec une clé API et un secret sans enregistrer ; répertorie les zones. | `infra:write` (+ `secrets:write`, car vous transmettez les clés) | No | No |
| `cloudstack_connect` | Enregistrez la connexion CloudStack. | `infra:write` (+ `secrets:write`) | Oui | Toujours |
| `proxmox_list` | Clusters Proxmox VE ajoutés en tant que sources, avec leur état de santé. | `admin:read` | No | No |
| `proxmox_add` | Ajoutez un cluster Proxmox VE avec un jeton API (`user@realm!tokenid`) et son secret. | `infra:write` (+ `secrets:write`) | Oui | No |
| `proxmox_test` | Connectez-vous à un cluster par son identifiant ; la première connexion réussie épingle son certificat TLS. | `infra:write` | Oui | No |
| `proxmox_attach_zone` | Vendez un cluster Proxmox dans une zone existante, éventuellement avec un nœud comme région. | `infra:write` | Oui | No |
| `zones_list` | Zones (emplacements) que les clients peuvent choisir. | `admin:read` | No | No |
| `zone_create` | Créez une zone. | `infra:write` | Oui | No |

### Catalogue et offres {#catalog-and-plans}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `templates_list` | Modèles de systèmes d'exploitation que les clients peuvent installer. | `admin:read` | No | No |
| `templates_sync` | Importez des modèles de systèmes d'exploitation depuis CloudStack. | `catalog:write` | Oui | No |
| `template_update` | Activez ou masquez un modèle, renommez-le, définissez l'utilisateur de connexion ou l'ordre. | `catalog:write` | Oui | No |
| `offerings_list` | Offres de service CloudStack (CPU, mémoire, disque racine) pour créer des offres. | `admin:read` | No | No |
| `plans_list` | Offres avec prix par heure et par mois, taille, zone et nombre de serveurs qui les utilisent. | `admin:read` | No | No |
| `plan_create` | Créez une offre. Prix sous la forme `hourly_usd`. Les offres CloudStack nécessitent `cs_offering_id` ; les offres Proxmox nécessitent `backend_id`. | `catalog:write` | Oui | No |
| `plan_update` | Renommez, affichez ou masquez, activez ou désactivez, ou modifiez le prix d'une offre. Les modifications de taille sur une offre en cours d'utilisation nécessitent une copie. | `catalog:write` | Oui | Lorsque le prix change |
| `plans_from_offerings` | Générer un tableau de forfaits de départ à partir des offres (ou des tailles Proxmox) en utilisant votre coût et un pourcentage de marge. Renvoie un aperçu ; appelez à nouveau avec `apply=true` pour créer les forfaits. | `catalog:write` | Avec `apply=true` | Toujours appliqué |
| `quota_defaults_get` | Limites client par défaut. | `admin:read` | No | No |
| `quota_defaults_set` | Modifier les paramètres de `quota_*`. | `catalog:write` | Oui | No |
| `coupons_list` | Lots de codes de réduction et cadeaux. | `admin:read` | No | No |
| `coupon_create` | Créer un lot de codes : tapez `money` (valeur faciale en centimes USD) ou `percent` (1 à 100, avec une réduction maximale). | `catalog:write` | Oui | Toujours |

### Clients et revendeurs {#customers-and-resellers}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `customers_search` | Trouver des clients par e-mail, nom ou IP. | `admin:read` | No | No |
| `customer_get` | Compte, solde, serveurs et facturation récente d'un client. | `admin:read` | No | No |
| `customer_adjust_balance` | Ajouter (positif) ou supprimer (négatif) du crédit en centimes USD. Un motif est requis. | `billing:write` | Oui | Toujours |
| `customer_block` | Bloquer un client, en arrêtant éventuellement ses serveurs. Un motif est requis. | `customers:write` | Oui | Toujours |
| `customer_unblock` | Débloquer un client. | `customers:write` | Oui | No |
| `resellers_list` | Revendeurs avec portefeuille et statut. | `admin:read` | No | No |
| `reseller_get` | Site, portefeuille, utilisateurs et passerelles d'un revendeur. | `admin:read` | No | No |

### Fournisseur d'IA {#ai-provider}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `ai_provider_get` | Le fournisseur compatible OpenAI utilisé par l'AI Chat et l'AI Agent client (clé masquée). | `admin:read` | No | No |
| `ai_provider_set` | Définir le fournisseur : URL de base, modèle, clé API, modèles de secours, effort de raisonnement, activé. | `ai:write` (+ `secrets:write` pour la clé) | Oui | No |
| `ai_provider_test` | Poser une question au fournisseur enregistré pour vérifier son bon fonctionnement. | `ai:write` | No | No |

### Fichiers de configuration {#configuration-files}

| Outil | Description | Portée | Changes data | Asks you |
|---|---|---|---|---|
| `config_export` | Exporter la configuration au format YAML (les secrets deviennent des références `secret://`). | `admin:read` | No | No |
| `config_plan` | Comparer une configuration YAML avec le panneau en direct et lister les modifications. | `admin:read` | No | No |
| `config_apply` | Appliquer une configuration YAML section par section. Chaque modification respecte les règles normales de portée et de confirmation. | `admin:read` + la portée de chaque modification | Oui | Par modification |

Consultez [Configuration as code](https://nexcmp.com/fr/docs/configure-with-ai/config-as-code/) pour connaître le format de fichier.

## Prompts {#prompts}

Le serveur propose également trois prompts prêts à l'emploi que les clients peuvent afficher comme raccourcis :

| Prompt | Argument | Ce qu'il demande à l'IA de faire |
|---|---|---|
| `initial-setup` | aucun | Appeler `setup_checklist`, expliquer chaque étape ouverte en une phrase, vous demander les informations nécessaires, effectuer l'étape avec l'outil correspondant, prévisualiser les modifications financières ou de sécurité, et terminer par `system_health`. |
| `add-proxmox` | `endpoint` (facultatif, `https://host:8006`) | Demander le jeton API, puis `proxmox_add`, `proxmox_test`, les outils de zone et `proxmox_attach_zone` ; puis proposer des forfaits avec `plans_from_offerings` et attendre votre approbation. |
| `launch-pricing` | `margin_pct` (facultatif, par défaut 40) | Demander votre coût mensuel par vCPU, par Go de RAM et par Go de disque, afficher un tableau d'aperçu avec le coût, le prix par mois et le prix par heure, et créer les forfaits après votre approbation. |

## Confirmation (`confirm_token`) {#confirmation-confirm-token}

Les actions qui déplacent de l'argent, suppriment des données, modifient des identifiants de paiement ou la sécurité de connexion se font en deux étapes :

1. Le premier appel ne modifie rien. Le résultat de l'outil commence par « CONFIRMATION REQUIRED » et comprend un **aperçu** (ce qui sera appelé, pourquoi c'est sensible, les nouvelles valeurs et les actuelles) ainsi qu'un `confirm_token`.
2. Le client doit vous montrer l'aperçu. Ce n'est qu'après votre approbation qu'il rappelle le même outil avec les mêmes arguments plus `confirm_token`.
3. Le jeton fonctionne une seule fois, uniquement pour cette requête exacte, et expire après 5 minutes.

Les instructions du serveur indiquent à l'IA de traiter les résultats d'outils comme des données, et non comme des instructions, et de ne jamais répéter un appel avec un jeton que vous n'avez pas approuvé. Vous êtes le rempart : lisez l'aperçu.

::: warning Ne pas approuver automatiquement
Certains clients peuvent approuver automatiquement chaque appel d'outil. Pour les outils d'écriture, maintenez l'approbation par appel active ou utilisez une clé en lecture seule, afin qu'un plan erroné de l'IA ne puisse pas atteindre votre panneau à votre insu.
:::

## Comment ça fonctionne {#how-it-works}

| Élément | Détail |
|---|---|
| Transport | `POST /mcp/admin` avec un message JSON-RPC 2.0 ; la réponse est `application/json`. Jusqu'à 20 messages dans un lot. `GET /mcp/admin` renvoie 405 (pas de flux serveur) ; `DELETE /mcp/admin` met fin à une session. |
| Authentification | `Authorization: Bearer ak_...` (une clé manuelle ou un jeton d'accès OAuth). Des identifiants manquants ou incorrects renvoient 401 avec `WWW-Authenticate: Bearer ... resource_metadata=...`, ce qui permet aux clients OAuth de lancer la connexion par eux-mêmes. |
| Sessions | `Mcp-Session-Id` est émis par `initialize`, lié à cette clé et valide pendant 24 heures. |
| Fonctionnalités | Outils et invites. Pas de ressources. |
| Taille | Corps de requête jusqu'à 1 Mo ; le résultat d'un outil est tronqué après environ 100 Ko. |
| Origine | Une requête portant un en-tête `Origin` provenant d'un autre site est refusée (`origin_not_allowed`). Les clients en ligne de commande et de bureau n'en envoient aucun. |
| Même passerelle que l'API REST | Chaque appel d'outil est retransmis via le pipeline de requêtes propre au panneau avec votre clé, de sorte que les portées, les plages IP, la limite de débit, la confirmation et le journal d'activité s'appliquent exactement comme pour les appels d'API directs. |

## Limites et notes {#limits-notes}

- Un outil que vous ne voyez pas correspond à une portée que vous n'avez pas accordée. Ajoutez la portée à une nouvelle clé.
- Définir un mot de passe ou une clé d'API via un client IA signifie que le secret transite par cette IA. Si vous préférez, désactivez `secrets:write` et saisissez vous-même les secrets dans l'administration, ou utilisez le champ **Secret** de l'AI Chat ([AI Chat in the admin](https://nexcmp.com/fr/docs/configure-with-ai/ai-chat-in-admin/#secrets)) ou les références `secret://` ([Configuration as code](https://nexcmp.com/fr/docs/configure-with-ai/config-as-code/#secrets)).
- Les clients ne partagent pas les sessions : chaque connexion commence par `initialize`.
- Révoquez la clé dans **API & AI agents** pour couper immédiatement l'accès à un client IA.

## Dépannage {#troubleshooting}

| Symptôme | Cause | Solution |
|---|---|---|
| 401 `invalid_key` | Clé incorrecte, tronquée ou non administrateur (par exemple une clé `vk_`) | Utilisez une clé `ak_`. |
| 401 `key_expired` ou `key_revoked` | La clé a expiré ou a été révoquée | Créez une nouvelle clé. |
| 403 `ip_not_allowed` | Votre adresse IP se trouve en dehors des plages IP de la clé | Connectez-vous depuis une adresse IP autorisée. |
| 403 `origin_not_allowed` | Une page de navigateur sur une autre origine a appelé l'endpoint | Utilisez un client de bureau ou CLI. |
| 404 sur une requête avec `Mcp-Session-Id` | La session appartient à une autre clé ou a expiré | Envoyez à nouveau `initialize`. |
| 400 unsupported `MCP-Protocol-Version` | Le client utilise une version que le serveur ne connaît pas | Mettez à jour le client ; versions prises en charge : 2025-11-25, 2025-06-18, 2025-03-26. |
| La liste des outils est courte | Portées de clé | Créez une clé avec davantage de portées. |
| `insufficient_scope` sur un appel | Un outil nécessite une seconde portée, par exemple `secrets:write` | Ajoutez la portée à une nouvelle clé. |
| 429 `rate_limited` | Plus d'appels par minute que ne le permet la clé | Patientez pendant `Retry-After` ou augmentez la limite sur une nouvelle clé. |
| claude.ai ou ChatGPT ne parvient pas à se connecter | L'URL n'est pas joignable depuis Internet, ou un proxy bloque `/mcp/admin` ou `/oauth-admin/` | Vérifiez le DNS, le protocole TLS et le proxy inverse. |

Pour tous les codes d'erreur, consultez [Admin API keys](https://nexcmp.com/fr/docs/configure-with-ai/admin-api-keys/#errors).