Développeurs/Serveur MCP

Serveur MCP Hostwolf

@hostwolf/mcp permet aux assistants IA de gérer vos serveurs de jeu Hostwolf. Il fonctionne avec Claude, Cursor, VS Code et tout autre client compatible avec le Model Context Protocol. Demandez par exemple :

• « Pourquoi mon serveur Minecraft a-t-il planté la nuit dernière ? »
• « Installe EssentialsX et redémarre. »
• « Sauvegarde Valheim, puis passe-le sur la branche de test publique. »
• « Bannis le joueur griefer123 et explique à tout le monde pourquoi. »
• « Redémarre tous les serveurs chaque jour à 4 h. »

Configuration#

1. Créez une clé API sur panel.hostwolf.net/account/api.
2. Connectez votre client. Vous pouvez utiliser le serveur hébergé sur https://hostwolf.net/mcp (rien à installer), ou l’exécuter vous-même à partir du téléchargement (nécessite Node.js 18+).

Hébergé : https://hostwolf.net/mcp#

Rien à installer, et toujours la dernière version. Votre client envoie votre clé à chaque requête ; nous ne la stockons jamais.

claude mcp add --transport http hostwolf https://hostwolf.net/mcp --header "Authorization: Bearer ptlc_your_key"

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hostwolf.net/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer ptlc_your_key" }
    }
  }
}

{
  "mcpServers": {
    "hostwolf": {
      "url": "https://hostwolf.net/mcp",
      "headers": { "Authorization": "Bearer ptlc_your_key" }
    }
  }
}

{
  "servers": {
    "hostwolf": {
      "type": "http",
      "url": "https://hostwolf.net/mcp",
      "headers": { "Authorization": "Bearer ptlc_your_key" }
    }
  }
}

Les options se mettent dans l’URL : https://hostwolf.net/mcp?readonly=1 n’expose que les outils de lecture, et ?servers=1a2b3c4d,5e6f7a8b limite l’assistant à ces serveurs. Si votre clé est limitée à certaines adresses IP, autorisez aussi 162.55.180.229, l’adresse du serveur hébergé.

L’exécuter vous-même#

Le même serveur en téléchargement. Il tourne sur votre ordinateur, donc votre clé ne le quitte jamais.

claude mcp add hostwolf -e HOSTWOLF_API_KEY=ptlc_your_key -- npx -y https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

{
  "servers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

Paramètres#

Pour le serveur exécuté par vous-même ; le serveur hébergé prend plutôt ?readonly=1 et ?servers= dans son URL.

Outils#

Vous pouvez désigner les serveurs par leur identifiant ou par leur nom (« mon serveur survie »). Chaque outil appelle l’API REST via le SDK ; tout ce qu’un outil ne sait pas encore faire n’est qu’à quelques lignes de code.

Consulter et diagnostiquer :

• list_servers : état, adresse et utilisation de la RAM.
• get_server : détails d’un serveur.
• get_console : dernières lignes de la console.
• diagnose_server : lance les vérifications « Fix my server ».
• list_players.

Contrôle :

• power_server : démarrer, arrêter, redémarrer ou forcer l’arrêt (kill).
• send_command.
• player_action : expulser, bannir, débannir ou diffuser un message.
• reinstall_server.

Fichiers :

• list_files.
• read_file : parcourt les fichiers longs page par page.
• write_file.
• rename_file.
• delete_files.

Sauvegardes :

• list_backups.
• create_backup.
• restore_backup.
• delete_backup.

Configuration :

• get_startup et set_startup_variable.
• get_game_settings et update_game_settings.
• get_game_versions et set_game_version.

Mods :

• search_addons.
• list_installed_addons.
• install_addon et uninstall_addon.
• search_modpacks et install_modpack.

Bases de données :

• list_databases : détails de connexion et qui peut se connecter depuis l’extérieur.
• create_database : la première base d’un serveur attend environ 40 secondes, le temps que le service de bases de données démarre.
• set_database_remote_access : autoriser les IP d’autres serveurs, ou toute personne qui a le mot de passe.
• rotate_database_password et delete_database.
• export_database et import_database : enregistrer un .sql.gz sur votre ordinateur, ou en charger un. Serveur auto-hébergé uniquement.

Les mots de passe restent masqués, sauf si vous demandez à votre assistant de les afficher.

Planifications :

• list_schedules.
• create_schedule.
• delete_schedule.

Compte :

• get_plans_and_prices : jeux, tailles d’offre et prix par région.
• list_orders.

Sécurité#

• Les outils qui modifient quelque chose sont signalés à votre client. Les outils destructifs sont marqués destructiveHint, pour que les clients demandent confirmation avant de les lancer : arrêt forcé, restauration, suppression de fichiers, de sauvegardes, de planifications ou de bases de données, import de base de données, réinstallation, changement de version, installation de modpack et écrasement de fichier.
• HOSTWOLF_READONLY=1 (ou ?readonly=1 sur l’URL hébergée) retire tous les outils qui modifient quelque chose.
• HOSTWOLF_SERVERS (ou ?servers=) limite l’assistant à certains serveurs.
• Le serveur hébergé vérifie votre clé auprès du panel, ne garde rien entre les requêtes et n’enregistre jamais les clés ni les arguments des outils. Il est limité en débit par adresse et par clé.
• Les clés API ne peuvent pas commander, résilier ou payer des serveurs. Ces actions se font uniquement dans le panel web.
• Vous pouvez créer une clé réservée à votre assistant et la révoquer à tout moment depuis le panel.

Dépannage#

• « Send your Hostwolf API key » (401) : le client n’a pas envoyé l’en-tête Authorization: Bearer ptlc_.... Vérifiez l’en-tête dans votre configuration.
• « This API key was rejected by the panel » (401) : la clé est erronée, incomplète ou révoquée. Copiez la clé entière, qui commence par ptlc_.
• « This API key has an IP allow-list… » (401) : le serveur hébergé appelle l’API depuis 162.55.180.229. Créez une clé qui autorise cette adresse, ou une clé sans liste d’adresses autorisées, ou exécutez le serveur vous-même.
• « Too many requests » (429) : le serveur hébergé accepte 300 requêtes par minute par adresse et 180 par clé. Les outils signalent aussi les limites propres à l’API, comme 2 sauvegardes par tranche de 10 minutes, avec le nombre de secondes à attendre.
• « Server busy » (503) : réessayez dans quelques secondes.
• Une tâche longue semble s’arrêter : chaque outil répond en moins de 50 secondes. Les sauvegardes, restaurations, réinstallations et installations de modpacks continuent en arrière-plan : demandez à votre assistant de vérifier avec get_server ou list_backups.
• Une nouvelle base indique « en cours de configuration » : create_database attend jusqu’à 2 minutes (75 secondes sur le serveur hébergé) que le service de bases de données démarre. S’il n’est pas prêt d’ici là, l’outil le dit, et la base apparaît peu après dans list_databases.

Mise à jour#

Le serveur hébergé est toujours à jour. Pour celui que vous exécutez vous-même, npx met le serveur en cache selon son URL ; il ne se met donc jamais à jour tout seul. Chaque version a sa propre URL, et le serveur consulte hostwolf.net/dl/index.json au démarrage. S’il existe une version plus récente, il l’indique dans ses journaux et l’ajoute au résultat de list_servers, pour que votre assistant vous prévienne. Pour mettre à jour, changez la version dans l’URL de votre configuration et redémarrez votre client.

Construit sur le SDK#

Les outils utilisent @hostwolf/sdk, inclus dans ce paquet. Pour intégrer le serveur dans votre propre application, installez les deux paquets :

npm install https://hostwolf.net/dl/hostwolf-sdk-0.1.8.tgz https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz

import { Hostwolf } from '@hostwolf/sdk';
import { createHostwolfMcp } from '@hostwolf/mcp/server';

Licence#

MIT