sspcloud-mcp — Agent Compute pour SSPCloud / Onyxia

▶ Présentation produit · Installer · Pour un agent IA · Changelog

Serveur MCP qui donne à un agent LLM (Claude Desktop, Claude Code, tout client MCP) un poste de travail distant sur SSPCloud : pousser un repo (local ou GitHub) dans un pod, écrire / exécuter / tester / évaluer du code, exploiter le GPU et des kernels Jupyter à état persistant, déployer des services, rapatrier les livrables — le tout piloté par des outils MCP.

Pourquoi

SSPCloud (Onyxia, INSEE) offre du calcul GPU gratuit, mais un agent LLM ne peut pas s'en servir seul :

• Un utilisateur SSPCloud standard a la policy stsonly → aucun droit kubectl (même en lecture dans son propre namespace) et l'API Onyxia PUT /my-lab/app est bloquée. Un agent ne peut donc ni lancer ni piloter un pod pour ce compte.

• Les pods Onyxia sont éphémères, sans port entrant, sans IP publique.

sspcloud-mcp lève ces verrous : il s'exécute avec un contexte admin (kubectl/helm dans un namespace disposant des droits), lance/scale les pods, et pilote leur kernel Jupyter — exposant tout cela à l'agent sous forme d'outils simples et bornés.

C'est précisément ce qui manque quand un agent dit « il faut lancer un service GPU depuis l'interface Onyxia, je ne peux pas le faire à ta place ».

Related MCP server: Ambient Code Platform MCP Server

Modes d'utilisation — quel mode pour qui

• L'hébergé durable est le mode « produit » : chacun lance son service dans son namespace, comme Deployment (redémarrage auto, jamais auto-suspendu), exposé en HTTPS/OAuth, utilisable depuis Claude Desktop et l'app mobile. Le serveur agit avec un ServiceAccount edit ; aucun droit kubectl côté PC requis.

• Le local est le plus rapide si vous avez déjà kubectl configuré (aucun pod à déployer).

Même code (sspcloud_mcp) dans les deux cas — seule la façade change (stdio vs HTTP+OAuth). Agent IA qui installe avec vous : voir AGENTS.md.

En un coup d'œil

Agent LLM (Claude Desktop / Code)
   │  outils MCP
   ▼
sspcloud-mcp  ──►  kubectl / helm (contexte admin)   → lance/scale les pods
   │           └►  kernel Jupyter (WebSocket)         → exec Python STATEFUL
   ▼
Pod(s) SSPCloud  ── git clone · pip · pytest · GPU · notebooks · checkpoints S3

• Exécution Python à état persistant : le modèle chargé, les variables, les imports survivent entre les appels d'outils (kernel Jupyter maintenu vivant).

• Shell via le kernel : git, pip, pytest… tournent dans le pod sans dépendance supplémentaire.

• Slot GPU arbitré : 1 GPU/utilisateur SSPCloud → bascule par projet avec préemption, environnement de chaque projet préservé (PVC).

Installation

Nouveau venu ? Deux guides d'installation individuelle (votre compte, votre namespace) :

• docs/INSTALL-IN-CLUSTER.md — illustré, service dans un pod SSPCloud (fonctionne même en compte restreint stsonly). Recommandé.

• docs/ONBOARDING.md — depuis un PC avec kubectl (compte avec droits).

Usage strictement individuel : chaque personne installe le service pour son propre namespace, avec son propre kubeconfig. Aucun compte central, aucun accès aux pods d'autrui.

git clone https://github.com/nic01asFr/sspcloud-mcp.git
cd sspcloud-mcp
pip install -e .            # cœur autonome (websockets)
# pip install -e .[service] # + outils de déploiement service_* (SDK Passerelle)

Prérequis runtime (côté machine qui héberge le serveur MCP) :

• kubectl et helm dans le PATH, avec un kubeconfig configuré pour SSPCloud (copié depuis datalab.sspcloud.fr → Mon compte → Kubernetes).

• Un contexte disposant des droits dans un namespace (compte admin). Voir docs/GUIDE.md pour la contrainte stsonly.

• Python ≥ 3.9.

Configuration client

Claude Desktop

%APPDATA%\Roaming\Claude\claude_desktop_config.json (Windows) — ajouter dans mcpServers :

"sspcloud-mcp": {
  "command": "sspcloud-mcp",
  "env": {
    "SSPCLOUD_NAMESPACE": "user-VOTRE_NS",
    "PASSERELLE_KUBE_CONTEXT": "VOTRE_CONTEXTE_ADMIN",
    "PASSERELLE_MCP_POD": "passerelle-mcp-dev-jupyter-python-0"
  }
}

Si sspcloud-mcp n'est pas installé (pip install), remplacez par "command": "python", "args": ["-m", "sspcloud_mcp.server"] avec "PYTHONPATH": "chemin/vers/sspcloud_mcp" dans env.

Redémarrer Claude Desktop complètement (quitter depuis la zone de notification).

Claude Code (.mcp.json de projet)

{
  "mcpServers": {
    "sspcloud-mcp": {
      "command": "sspcloud-mcp",
      "env": {
        "SSPCLOUD_NAMESPACE": "user-VOTRE_NS",
        "PASSERELLE_KUBE_CONTEXT": "VOTRE_CONTEXTE_ADMIN",
        "PASSERELLE_MCP_POD": "passerelle-mcp-dev-jupyter-python-0"
      }
    }
  }
}

Variables d'environnement

Prise en main (workflow type)

session_start()                              # attache le pod substrat (env PASSERELLE_MCP_POD)
push_repo(source="github.com/org/repo")      # git clone dans le pod (ou chemin local)
exec(code="import torch; model = load()")    # Python — reste en mémoire
exec(lang="bash", code="pytest -q")          # shell dans le pod
gpu_switch(project="mon-projet")             # bascule le slot GPU vers un pod GPU
exec(code="preds = model(batch)")            # inférence / éval sur GPU
pull_artifact(path="results/out.gpkg")       # rapatrie le livrable en local
session_stop(session_id=...)                 # libère kernel + port-forward

Référence des outils (24)

Sessions & exécution

Code & fichiers

GPU (slot unique arbitré)

Projets & pods

Exposition HTTPS publique

Déploiement de services (extra [service])

Guide détaillé, exemples et dépannage : docs/GUIDE.md.

Architecture

• Transport : port-forward vers le kernel Jupyter du pod (court-circuite l'ingress K8s) ; le token Jupyter = le security.password du pod. En pod (in-cluster), le kernel est joint via le DNS interne.

• Cœur autonome : websockets uniquement. jupyter_protocol (protocole ZMQ binaire) et les helpers helm sont vendorés.

• Outils service_* : reposent sur passerelle-sdk (extra [service]).

Détails de conception : voir la note d'architecture d'origine dans le dépôt Passerelle (docs/mcp-agent-compute-plan.md).

Limites connues

• Le transport URL publique + token (sans kubectl) fonctionne en REST mais le WebSocket kernel ne traverse pas l'ingress Onyxia de façon fiable → utiliser le port-forward (contexte admin). Résolu nativement par l'hébergement in-cluster (V2).

• Cold start GPU ~5-8 min à la première allocation d'un pod GPU.

• 1 seul GPU par utilisateur SSPCloud → gpu_switch arbitre le slot (préemption).

Hébergement durable + connecteur OAuth — livré ✅

Le serveur s'héberge dans le namespace SSPCloud de l'utilisateur comme Deployment Kubernetes (process principal du pod) : redémarrage automatique, jamais auto-suspendu, survit à la fermeture des pods Jupyter. Exposé en connecteur MCP OAuth (Streamable HTTP + OAuth 2.1 + DCR RFC 7591 + PKCE, CORS pour le flux navigateur de claude.ai), déclarable dans Claude Desktop et l'app mobile.

Deux voies d'installation. Les deux tirent l'image ghcr.io/nic01asfr/sspcloud-mcp et le chart Helm publié sur GitHub (pas un clone GitLab au démarrage du pod) :

• Catalogue Onyxia (recommandé, un clic) — source Helm https://raw.githubusercontent.com/nic01asFr/sspcloud-mcp/main/helm-repo. Onyxia crée SA dédié + RoleBinding edit, et le service apparaît dans « Mes services » (notes : URL du connecteur + clé API).

• CLI — depuis un pod lancé en kubernetes.role: edit :

curl -fsSL https://raw.githubusercontent.com/nic01asFr/sspcloud-mcp/main/install.sh | bash

Le script enregistre aussi le service dans Mes services. Voir docs/INSTALL-IN-CLUSTER.md et AGENTS.md.

scripts/mcp_expose.sh (lancement dans le terminal) reste pour un test rapide, mais il est fragile (tombe en ~10 min) — préférez la voie durable ci-dessus.

Licence

MIT — voir LICENSE.