---
title: Serveur MCP
description: Connectez des assistants IA à l'API de votre installation via le point de terminaison MCP intégré à /mcp — authentification, configuration client, outils et règles de sécurité.
url: https://nexcmp.com/fr/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Serveur MCP {#mcp-server}

> **Où dans le portail :** API reference › Tools (`https://<your-domain>/apidoc`) affiche le point de terminaison et les extraits pour le client ; les clés sont créées dans API keys (`/api-keys`). Il n'y a aucun paramètre dans l'admin : le point de terminaison fait partie du panneau.

## Description {#what-it-does}

Le **Model Context Protocol (MCP)** permet à un assistant IA d'appeler des outils. NexCMP propose un point de terminaison MCP sur `https://<your-domain>/mcp`. Chaque opération d'API publique devient un **outil** (`vm_list`, `vm_start`, `billing_wallet`, ...), de sorte qu'un client peut demander à son assistant « quelles sont mes VM en cours d'exécution ? » ou « arrête la VM de staging ». L'assistant agit exclusivement avec la clé API et les autorisations du client.

::: tip Vous configurez NexCMP vous-même avec l'IA ?
Cette page concerne le point de terminaison MCP **client** (`/mcp`). Pour permettre à un assistant IA de configurer votre propre panneau en tant qu'administrateur, consultez [Configure with AI](https://nexcmp.com/fr/docs/configure-with-ai/mcp-admin/) (point de terminaison `/mcp/admin`, clés d'administration `ak_`).
:::

## Prérequis {#requirements}

| Élément | Prérequis |
|---|---|
| Serveur | Rien à installer : le point de terminaison est desservi par le panneau et accessible partout où le panneau l'est. Votre proxy inverse doit transmettre `/mcp` au panneau. |
| Client | Une [API key](https://nexcmp.com/fr/docs/developers/api-keys/) (`vk_...`) disposant des portées nécessaires à l'assistant. |
| Client | Un client MCP prenant en charge le transport **Streamable HTTP** et un en-tête `Authorization` personnalisé : Claude Code, Claude Desktop (via le pont `mcp-remote`), Cursor, VS Code en mode agent Copilot et similaires. |
| Versions du protocole | 2025-11-25, 2025-06-18 et 2025-03-26. |

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

Rien de particulier, si ce n'est de s'assurer que `https://<your-domain>/mcp` n'est bloqué ni par un pare-feu ni par une règle de proxy. Un client MCP basé sur un navigateur provenant d'une autre origine est refusé à moins que cette origine ne soit autorisée ; les clients en ligne de commande et de bureau n'envoient aucun en-tête `Origin` et fonctionnent tels quels.

## Connexion (côté client) {#connect-customer-side}

1. Créez une clé API dans le portail (**API keys › Create key**) en ne sélectionnant que les portées que vous souhaitez autoriser pour l'assistant, avec une courte durée de validité et, si possible, une restriction IP.
2. Ajoutez le serveur à votre client. Remplacez `cloud.example.com` et la clé.

   **Claude Code**

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

   **Cursor** (`~/.cursor/mcp.json` ou `.cursor/mcp.json` ; définissez `CLOUD_API_KEY` dans l'environnement à partir duquel Cursor démarre) :

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop** (nécessite Node.js 18+ ; `claude_desktop_config.json`), via le pont `mcp-remote` :

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   Écrivez l'en-tête sans espace après les deux-points et placez toute la valeur dans la variable d'environnement, comme ci-dessus.

3. Redémarrez le client et demandez-lui de lister vos outils.


Vérifiez la connexion sans client :

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

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

| Élément | Détail |
|---|---|
| Endpoint | `POST /mcp` avec un message JSON-RPC 2.0 ; la réponse est `application/json`. `GET /mcp` répond par 405 (pas de flux serveur à client) ; `DELETE /mcp` met fin à la session. |
| Authentification | Seul `Authorization: Bearer vk_...` (les jetons de session, les cookies et les clés d'administration sont refusés avec un code 401 et un en-tête `WWW-Authenticate: Bearer`). |
| Session | `Mcp-Session-Id` est émis par `initialize`, lié à cette clé et valide pendant 24 heures ; au maximum 16 sessions par clé. |
| Outils | Un par opération d'API publique visible par la clé. Le nom de l'outil correspond à la commande CLI en remplaçant les espaces et les tirets par `_` (`vm firewall add` devient `vm_firewall_add`) et équivaut au champ OpenAPI `operationId`. Un outil n'est listé que lorsque la clé possède sa portée et que le module est activé. |
| Fonctionnalités | Outils uniquement (pas de ressources ni de prompts). |
| Taille | Corps de requête jusqu'à 1 Mo ; texte de résultat d'outil jusqu'à environ 100 Ko (le reste est tronqué avec une note) ; un appel prend au maximum 55 secondes. |

### Règles de sécurité {#safety-rules}

- **Même passerelle que l'API REST.** Chaque `tools/call` passe par le pipeline de requêtes propre au panneau : portée, site, restriction IP, limitation de débit, idempotence, vérifications de propriété (404 pour les ressources d'autrui) et quotas s'appliquent tous. Le protocole MCP ne peut rien accorder que la clé ne possède pas.
- **Confirmation.** Les outils payants, destructifs ou renvoyant des informations d'identification (tickets de console, kubeconfig, secrets S3 ou SSH, réinitialisations de mot de passe, nouvelles clés) nécessitent l'argument `confirm: true`. La description de l'outil indique à l'assistant de ne le transmettre qu'après approbation de l'utilisateur, empêchant ainsi toute instruction dissimulée dans une page web ou un journal de l'exécuter de son propre chef.
- **Idempotence.** Les outils payants acceptent `idempotency_key` ; si cet argument est omis, une clé stable est dérivée du nom de l'outil et de ses arguments, empêchant qu'une nouvelle tentative identique ne soit facturée deux fois.
- **Non exposés en tant qu'outils :** les points de terminaison de streaming (le chat de l'AI Agent), les tickets WebSocket ponctuels pour SSH ou console, les téléchargements binaires et les points de terminaison de l'application VPN (`/v1/ext/*`).
- **Jamais possible :** l'API ne permet en aucun cas d'effectuer des recharges, de changer de mot de passe, de supprimer le compte ou de créer des clés, ce qu'aucun assistant ne peut donc faire.

### Limites {#limits}

| Limite | Valeur par défaut |
|---|---|
| Appels d'outils par clé | 60 par minute |
| Requêtes MCP par clé | 240 par minute |
| Plus les limites normales de clé et de compte | Voir [REST API](https://nexcmp.com/fr/docs/developers/api/#rate-limits) |

En cas de dépassement de la limite, le point de terminaison renvoie une erreur HTTP 429 avec une erreur JSON-RPC et `Retry-After`.

## Vérification {#verify}

1. La commande `curl` ci-dessus renvoie un résultat JSON-RPC avec une liste `tools`. Seuls les outils correspondant aux portées de la clé apparaissent.
2. Dans votre client, demandez "list my VMs" : l'assistant appelle `vm_list` et affiche le résultat.
3. Dans le portail, l'heure **Last used** de la clé est mise à jour et les appels d'écriture apparaissent dans le journal **Key usage log**.

## Limites et notes {#limits-notes}

- **Connexion par navigateur (OAuth).** La page de référence décrit également la connexion via le navigateur pour les clients prenant en charge l'OAuth MCP. Dans une instance NexCMP installée, la méthode prise en charge et testée est la clé API (ou `cmp login` pour la CLI).
- **Les sites revendeurs** n'affichent pas la section MCP ; leurs clients utilisent le domaine du revendeur pour l'API.
- **Moindre privilège.** Créez une clé dédiée par assistant avec des portées en lecture en premier ; n'ajoutez des portées en écriture que lorsque cela est nécessaire.
- Révoquez la clé dans **API keys** pour couper immédiatement l'accès de l'assistant.

## Dépannage {#troubleshooting}

| Symptôme | Cause | Solution |
|---|---|---|
| 401 avec `WWW-Authenticate: Bearer` | Aucune clé, clé erronée ou jeton de session | Envoyer `Authorization: Bearer vk_...`. |
| 403 concernant `Origin` | Page de navigateur sur une autre origine | Utilisez un client de bureau ou CLI, ou demandez à votre administrateur d'autoriser l'origine (`mcp_allowed_origins`). |
| 404 sur une requête avec `Mcp-Session-Id` | La session appartient à une autre clé ou a expiré | Exécutez à nouveau `initialize`. |
| 405 sur `GET /mcp` | Attendu : le serveur ne dispose d'aucun flux d'événements | Utilisez uniquement POST (les clients le font automatiquement). |
| La liste des outils est courte | Portées ou modules de la clé | Ajoutez des portées à la clé ; activez le module. |
| L'outil indique qu'il a besoin de `confirm: true` | Outil payant, de suppression ou sensible | L'assistant doit définir `confirm` après votre approbation. |
| 429 | Limite de débit MCP ou de la clé | Attendre `Retry-After`. |
| Le client ne peut pas se connecter avec un en-tête | Client sans prise en charge des en-têtes personnalisés | Utilisez le pont `mcp-remote`. |