Traduction automatique, non relue par un locuteur natif. L'anglais fait foi.

API et intégrationsModifier sur GitHubSource : docs/deploy/mcp-http.md

Exécuter kshana-mcp via HTTP (auto-hébergé)

Un passage nommant des clients d'IA tiers est omis ici ; il figure dans docs/deploy/mcp-http.md sur GitHub.

Kshana n'héberge aucun point d'accès. Il n'existe aucun serveur kshana partagé vers lequel diriger un client. Vous l'exécutez sur votre propre machine, conteneur ou projet cloud, et vous en possédez le contrôle d'accès et le coût. Le serveur 0.40.0 est celui de ce dépôt : ses chiffres portent leurs libellés VALIDATED ou MODELLED exactement comme via stdio.

Les valeurs par défaut sûres#

Contrôle Comportement
Adresse de liaison Bouclage local seulement (127.0.0.1, ::1). Un port seul (--http 8080) signifie 127.0.0.1:8080.
Non-loopback Exige --allow-remote et un jeton porteur dans la variable d'environnement KSHANA_MCP_HTTP_TOKEN (16 caractères ou plus). Sans les deux, le serveur refuse de démarrer. Avec les deux, il affiche un avertissement indiquant qu'il écoute au-delà de cette machine.
Authentification Authorization: Bearer <token> à chaque requête lorsqu'un jeton est défini (il peut aussi l'être sur le bouclage local). Comparé en temps constant. Absent ou erroné : 401.
Système de fichiers Aucun. Les outils de fichiers IQ (iq_*) sont désactivés en mode HTTP quoi que dise KSHANA_MCP_IQ_DIR ; tout autre outil prend son scénario en ligne et refuse un scénario qui nomme un fichier. Aucun argument d'outil ne lit ni n'écrit un chemin.
Taille du corps --max-body-bytes, par défaut 5 Mio (le plafond d'un scénario est de 4 Mio). Au-delà : 413, que la longueur soit déclarée ou que le corps soit fragmenté.
Délai de réponse --request-timeout-secs, par défaut 120. Au-delà : 408. Cela borne la durée pendant laquelle un appelant attend, non le travail : une exécution déjà en cours ne peut pas être arrêtée, elle se poursuit donc après le 408 et se termine en arrière-plan.
Concurrence --max-concurrent, par défaut 8. Au-delà, une requête reçoit aussitôt 503 avec Retry-After ; aucune n'est mise en file.
Réserve de travail Chaque appel d'outil s'exécute sur un fil bloquant dans une réserve de --max-concurrent emplacements, jamais sur les travailleurs asynchrones, de sorte qu'une longue exécution ne peut pas empêcher le serveur de répondre. Un emplacement n'est libéré que lorsque l'exécution elle-même se termine, non lorsque l'appelant abandonne : les exécutions abandonnées ne peuvent donc pas s'accumuler au-delà de la taille de la réserve, et un appel qui trouve la réserve pleine est refusé comme occupé.
Budget de travail Un scénario qui demande bien plus que les exemples fournis est refusé avant son exécution : plus de 1000 réalisations Monte Carlo (runs), une grille de paramètres de plus de 1000 nœuds, plus de 5000 exécutions membres (nœuds de grille multipliés par réalisations), ou une grille temporelle de plus de 2 millions d'époques. L'erreur nomme le champ à diminuer. Le même budget s'applique via stdio ; la ligne de commande kshana n'en a aucun.
CORS Aucun en-tête Access-Control-* n'est jamais envoyé. Une requête portant un en-tête Origin est refusée (403) à moins d'être nommée avec --allow-origin <scheme://host[:port]> ; * n'est pas accepté.
En-tête Host Vérifié par rapport aux noms de bouclage, ou à l'adresse de liaison plus chaque --allowed-host. Derrière un proxy ou sur une URL de plateforme, passez --allowed-host your.domain. Tout le reste : 403.
Sessions Aucune. Chaque POST reçoit une réponse JSON ; aucune table de sessions et aucun flux d'événements envoyés par le serveur n'est gardé ouvert.

Le TLS n'est pas terminé par kshana-mcp. Lorsqu'il est joignable au-delà d'une seule machine, placez HTTPS devant (le TLS de votre plateforme, ou un proxy inverse) et gardez le jeton secret ; un jeton porteur sur HTTP en clair peut être lu sur le réseau.

Local#

kshana-mcp --http 127.0.0.1:8080

Configuration du client (un client par URL ; n'ajoutez l'en-tête que si un jeton est défini) :

{ "mcpServers": { "kshana": { "url": "http://127.0.0.1:8080/mcp",
    "headers": { "Authorization": "Bearer ${KSHANA_MCP_HTTP_TOKEN}" } } } }

Docker#

export KSHANA_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 -e KSHANA_MCP_HTTP_TOKEN \
  ghcr.io/ashfordeou/kshana-mcp:0.40.0 \
  --http 0.0.0.0:8080 --allow-remote --allowed-host localhost:8080 --allowed-host 127.0.0.1:8080

À l'intérieur du conteneur, le serveur doit écouter sur 0.0.0.0, il lui faut donc --allow-remote et le jeton. Publier le port sous la forme 127.0.0.1:8080:8080 le garde sur votre machine ; ne retirez le 127.0.0.1: que si vous voulez l'exposer, et terminez alors le TLS devant. Des modèles pour docker compose, Fly.io et Cloud Run se trouvent dans mcp-http/.

Modèles (vous les déployez ; Kshana n'en exécute aucun)#

Chacun exécute l'image publiée, règle --allowed-host sur le nom d'hôte de la plateforme que vous remplacez dans le fichier, et s'appuie sur la plateforme pour HTTPS.

Fixez une limite de CPU et de mémoire sur la plateforme#

Le délai, la réserve et le budget bornent la quantité de travail admise, mais un appel admis peut encore occuper un cœur pendant longtemps et un gros résultat peut utiliser des centaines de mégaoctets. Mettez aussi une limite stricte sur le conteneur : les modèles demandent 2 CPU et 1 Gio (cpus et mem_limit dans Compose, [[vm]] dans Fly, resources.limits dans Cloud Run). Gardez --max-concurrent à la valeur du nombre de CPU ou en dessous.

Ce que ce n'est pas#

  • Pas un service multilocataire. Quiconque détient le jeton exécute des simulations sur votre matériel ; il n'y a pas de quotas par utilisateur au-delà des limites ci-dessus.
  • À titre consultatif, et non un équipement de navigation homologué : l'opérateur reste responsable de la navigation. Les sorties du simulateur sont des chiffres modélisés ou validés destinés à l'analyse, comme partout ailleurs dans Kshana.