Serveur MCP

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

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.

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 (point de terminaison /mcp/admin, clés d'administration ak_).

Prérequis

É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 (`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

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)

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.

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.

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

É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é

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

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

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

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.
Dans votre client, demandez "list my VMs" : l'assistant appelle vm_list et affiche le résultat.
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

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

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

Serveur MCP ​

Description ​

Prérequis ​

Préparer l'infrastructure ​

Connexion (côté client) ​

Comment ça fonctionne ​

Règles de sécurité ​

Limites ​

Vérification ​

Limites et notes ​

Dépannage ​