Serveur MCP Coolify

Coolify intègre un serveur MCP, un point de terminaison Model Context Protocol à /mcp sur votre instance. Une fois que vous l'activez et créez un jeton d'API, un agent de codage IA comme Claude, Cursor ou Codex peut créer un projet sur votre serveur MapleDeploy, ajouter votre application et sa base de données, définir les variables d'environnement et la déployer. Il peut aussi lire les journaux, expliquer un déploiement échoué, revenir en arrière, repérer les ressources en mauvais état et vérifier que vos sauvegardes et tâches planifiées ont roulé.

Le serveur MCP est désactivé jusqu'à ce que vous l'activiez. Ce guide couvre son activation, la création d'un jeton, la connexion d'un client et sa désactivation.

Une première session typique

Avec un jeton doté des droits de lecture, de déploiement et d'écriture, une seule demande à votre client remplace une douzaine de clics :

Crée un projet de préproduction pour ce dépôt avec une base de données Postgres, ajoute les variables d'environnement de .env.example et déploie-le.

Le client crée le projet et un environnement de préproduction, crée l'application à partir de votre dépôt Git et une base de données Postgres à côté, ajoute chaque variable d'environnement que votre application attend, lance le déploiement et lit la sortie de build. Si le build échoue, il peut vous dire pourquoi, corriger la cause et redéployer. Les URL de connexion ne sont pas renvoyées au client : indiquez-lui comment votre application doit joindre la base de données, ou définissez cette variable vous-même.

Ce qu'un client connecté peut faire

Les outils qu'un client peut appeler dépendent des droits du jeton que vous lui donnez. Le déploiement et la lecture sont des droits distincts : un jeton qui n'a que le droit de déploiement peut agir sur vos ressources, mais ne peut pas les lire.

Un jeton de déploiement peut déployer et redéployer vos applications, y compris les aperçus de demandes de tirage si vous les utilisez, annuler un déploiement en cours, et démarrer, arrêter et redémarrer vos ressources. Il peut aussi ramener une application à une image antérieure. Pour lister les images parmi lesquelles choisir, il faut le droit de lecture.
Un jeton de lecture peut lister vos ressources et les noms de leurs variables d'environnement, parcourir l'historique des déploiements, repérer les ressources en mauvais état et voir quand les sauvegardes et tâches planifiées ont roulé. Il ne renvoie pas la valeur des variables d'environnement.
La lecture des journaux de service, de la sortie de build d'un déploiement et des messages de sauvegarde ou de tâche exige un jeton read:sensitive. Un jeton read:sensitive peut aussi lire la valeur des variables d'environnement.
Un jeton d'écriture peut créer et modifier des projets, des environnements, des applications, des bases de données, des services, des variables d'environnement, des serveurs, des clés privées, des sauvegardes et du stockage. Il peut aussi commander un serveur payant auprès d'un fournisseur infonuagique dont vous avez enregistré le jeton dans Coolify. À partir de Coolify 4.6, il peut aussi enregistrer et modifier des jetons d'intégration pour Cloudflare, Doppler, Infisical et Vault, et ajouter ou remplacer des enregistrements DNS dans les zones Cloudflare que joint un jeton enregistré.
Supprimer exige le droit delete à partir de Coolify 4.6. Les jetons qui avaient le droit write quand votre instance est passée à 4.6 ont aussi reçu le droit delete. Avant 4.6, un jeton d'écriture peut supprimer, et supprimer une application, une base de données ou un service exige aussi le droit de déploiement.

Un client ne voit que les outils et les actions que son jeton peut utiliser, sauf certains outils de lecture, visibles pour tous les jetons. En appeler un sans le droit de lecture échoue avec une erreur indiquant un droit manquant.

Le serveur MCP inclut aussi deux invites guidées, l'une pour diagnostiquer une application et l'autre pour expliquer un déploiement échoué. Les clients qui prennent en charge les invites MCP les proposent comme commandes toutes prêtes.

Si un client doit à la fois agir et lire, son jeton a besoin des deux droits. Un jeton root peut faire tout ce qui précède.

Activer le serveur MCP

Connectez-vous au tableau de bord MapleDeploy.
Ouvrez le serveur et allez à l'onglet Outils.
Sous Serveur MCP, sélectionnez Activer le serveur MCP.
Lisez l'avertissement sur ce qu'un point de terminaison activé expose, puis confirmez.

Seuls les propriétaires et administrateurs de l'organisation peuvent modifier ce paramètre.

Créer un jeton d'API Coolify

Le point de terminaison MCP s'authentifie avec un jeton d'API Coolify. Les droits du jeton décident de ce qu'un client connecté peut faire.

Ouvrez votre tableau de bord Coolify. Le lien se trouve sur la page de détails de votre serveur.
Allez à Keys & Tokens puis API Tokens.
Créez un jeton et choisissez ses droits. Coolify propose Root, Write, Deploy, Read et Read sensitive data (read:sensitive), et, à partir de 4.6, Delete. Un jeton qui a le droit deploy sans le droit read ne peut ni lister vos ressources ni lire les journaux. Ajoutez read si votre client a aussi besoin de la configuration, et read:sensitive s'il a besoin des journaux. Commencez par le minimum dont vous avez besoin.
Copiez le jeton. Coolify ne l'affiche qu'une fois.

Le point de terminaison MCP n'a pas besoin de l'API REST de Coolify : vous pouvez créer un jeton et l'utiliser quand l'API est désactivée.

Connecter votre client

Votre point de terminaison est votre adresse Coolify suivie de /mcp. Une fois le serveur MCP activé, l'onglet Outils l'affiche avec un bouton pour le copier :

https://votre-serveur.mapledeploy.ca/mcp

Chaque client a besoin de deux choses : cette URL, et votre jeton d'API transmis comme jeton porteur. Remplacez VOTRE_JETON ci-dessous par le jeton que vous avez copié.

Claude Code. Exécutez :

claude mcp add --transport http coolify https://votre-serveur.mapledeploy.ca/mcp --header "Authorization: Bearer VOTRE_JETON"

Cursor. Ajoutez le serveur à ~/.cursor/mcp.json. Utilisez ce fichier global plutôt que le .cursor/mcp.json d'un projet, pour que le jeton ne se retrouve jamais dans un dépôt.

{
  "mcpServers": {
    "coolify": {
      "url": "https://votre-serveur.mapledeploy.ca/mcp",
      "headers": {
        "Authorization": "Bearer VOTRE_JETON"
      }
    }
  }
}

Codex. Codex lit le jeton dans une variable d'environnement. Définissez-la là où Codex s'exécute, par exemple dans le profil de votre shell, puis ajoutez le serveur :

export COOLIFY_TOKEN=VOTRE_JETON
codex mcp add coolify --url https://votre-serveur.mapledeploy.ca/mcp --bearer-token-env-var COOLIFY_TOKEN

Une fois connecté, demandez au client de déployer une application, de récupérer les journaux d'un service ou d'expliquer pourquoi le dernier déploiement a échoué. Ce qu'il peut faire dépend des droits du jeton, décrits plus haut.

Le désactiver

Retournez à l'onglet Outils du serveur et sélectionnez Désactiver le serveur MCP. Le point de terminaison cesse de répondre immédiatement. La désactivation ne supprime pas vos jetons d'API; révoquez dans Coolify, sous Keys & Tokens puis API Tokens, tout jeton dont vous n'avez plus besoin.

À garder en tête

Tout jeton d'API Coolify de votre instance peut joindre le point de terminaison une fois activé, y compris les jetons en lecture seule. Gardez les droits des jetons aussi restreints que la tâche l'exige, et ne donnez write, delete ou root à un client que s'il doit modifier votre configuration.
Le paramètre Allowed IPs, sous Settings puis Advanced, s'applique au point de terminaison MCP comme à l'API REST.
Le risque réaliste est l'injection d'invite atteignant un client connecté. Avec un jeton d'écriture ou de suppression, elle peut aller jusqu'à modifier ou supprimer des ressources et commander des serveurs. Soyez donc délibéré sur ce que vous connectez et ce que vous y collez. Les actions destructrices exigent une confirmation explicite dans l'appel, mais c'est le client qui la fournit : elle ne remplace pas un jeton restreint.
Les journaux peuvent contenir des secrets, et tout ce que lit le client fait partie de sa conversation avec son fournisseur d'IA.
Vous pouvez désactiver le point de terminaison à tout moment depuis l'onglet Outils.