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 client de codage IA comme Claude Code, Cursor ou Codex peut déployer vos applications, démarrer et arrêter des ressources, et lire les journaux sur votre serveur MapleDeploy. Il peut aussi expliquer un déploiement échoué, 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.
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.
- 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 jamais 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.
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.
Donnez au client le jeton le moins puissant possible pour sa tâche. S'il doit à la fois agir et lire, son jeton a besoin des deux droits.
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. Si vous ne voyez pas le contrôle, votre serveur a peut-être besoin d'une mise à jour de Coolify avant qu'il apparaisse; il s'affiche dans l'onglet Outils une fois la mise à jour appliquée.
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 read, read:sensitive, write, write:sensitive, deploy et root. 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.
Si la création de jeton est masquée, l'API REST de Coolify est désactivée sur votre instance. Activez-la sous Settings puis Advanced dans Coolify, puis créez le jeton. Activer l'API REST ouvre aussi la surface REST de Coolify, alors désactivez-la de nouveau si vous n'en avez pas besoin.
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
Un serveur MCP activé est une vraie capacité, alors traitez-le comme telle.
- 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.
- Le risque réaliste est l'injection d'invite atteignant un client connecté. Soyez délibéré sur ce que vous connectez et ce que vous y collez.
- Le point de terminaison renvoie les noms des variables d'environnement, jamais leurs valeurs. Les journaux peuvent tout de même contenir des secrets, et un jeton read:sensitive peut lire les journaux.
- Vous pouvez désactiver le point de terminaison à tout moment depuis l'onglet Outils.