Docs/ Assistant IA/ Serveur MCP

Serveur MCP

Connectez Claude Desktop, Claude Code, Cursor ou tout client compatible MCP à sh0 et gérez vos déploiements en langage naturel.

Qu'est-ce que MCP

Le Model Context Protocol (MCP) est un standard ouvert pour connecter les assistants IA à des outils et sources de données externes. Au lieu de copier-coller la sortie du terminal dans une fenêtre de chat, MCP permet à votre assistant IA d'interagir directement avec sh0 -- lister les apps, lire les logs, déclencher des déploiements et diagnostiquer les problèmes.

sh0 inclut un serveur MCP intégré exposé sur POST /mcp utilisant le transport Streamable HTTP. Tout client prenant en charge MCP peut s'y connecter avec rien de plus qu'une URL et une clé API.

Connecter Claude Desktop

Ajoutez ce qui suit dans votre fichier de configuration Claude Desktop à ~/.claude/claude_desktop_config.json :

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Remplacez your-server.com par l'adresse de votre serveur sh0 et sh0_your_api_key par une clé API valide. Redémarrez Claude Desktop pour prendre en compte la nouvelle configuration.

Connecter Claude Code

Pour Claude Code (le CLI), ajoutez la même configuration dans ~/.claude.json sous la clé mcpServers :

~/.claude.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Une fois configuré, Claude Code découvrira et utilisera automatiquement les outils sh0 lorsque c'est pertinent pour vos prompts.

Connecter Cursor

Dans Cursor, ouvrez Settings → MCP et ajoutez un nouveau serveur avec la même configuration JSON :

Cursor MCP Settings

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

La configuration est identique pour les trois clients. Tout outil compatible MCP prenant en charge le transport Streamable HTTP fonctionnera avec la même URL et les mêmes identifiants.

Tip

Vous pouvez tester votre connexion MCP avec :

curl -X POST https://your-server/mcp -H 'Authorization: Bearer sh0_xxx' -H 'Content-Type: application/json' -d 'undefined,"clientInfo":undefined}}'

Portées des clés API

Les clés API contrôlent les outils auxquels l'assistant IA peut accéder. Chaque clé se voit attribuer une portée qui détermine ses permissions :

Portée	Outils	Description
`read`	37 outils	Lister et inspecter les apps, services, domaines, logs et métriques. Aucune modification autorisée.
`standard`	Lecture + écriture	Tout ce qui est en lecture, plus créer des apps, déclencher des déploiements, mettre à jour les variables d'environnement et gérer les domaines.
`admin`	Les 103 outils	Accès complet incluant les paramètres serveur, la gestion des utilisateurs, les opérations de sauvegarde et les actions destructives.

Pour créer une clé API, naviguez vers Settings → API Keys dans le tableau de bord. Choisissez la portée appropriée en fonction de ce que vous souhaitez que l'IA puisse faire. Pour la plupart des workflows de développement, standard offre le bon équilibre entre capacité et sécurité.

Warning

N'utilisez la portée admin que lorsque l'IA a besoin d'effectuer des opérations au niveau du serveur. Pour le développement quotidien, standard est recommandé.

Découverte automatique

Les 103 outils sont automatiquement découverts par les clients MCP. Aucun enregistrement manuel d'outils n'est nécessaire. Quand un client se connecte, il appelle la méthode tools/list, et sh0 répond avec le catalogue complet des outils -- noms, descriptions et définitions de paramètres en JSON Schema.

La liste des outils est filtrée en fonction de la portée de la clé API. Une clé à portée read ne verra que les 37 outils en lecture seule, tandis qu'une clé admin voit les 103.

Gestion des sessions

Le serveur MCP utilise des sessions pour maintenir l'état entre plusieurs requêtes au sein d'une conversation. Chaque session est identifiée par un UUID v4 retourné dans l'en-tête de réponse Mcp-Session-Id après l'appel initialize.

Les clients doivent inclure cet en-tête dans toutes les requêtes suivantes. Détails de la session :

Format d'ID : UUID v4 (ex. : a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d)
TTL : 1 heure d'inactivité
Éviction : Paresseuse -- les sessions expirées sont nettoyées lors de la création de nouvelles sessions
Portée : Chaque session hérite de la portée de la clé API utilisée lors de l'initialisation

Dépannage

Problèmes courants lors de la connexion au serveur MCP :

Connexion refusée

Vérifiez que le serveur sh0 est en cours d'exécution et que le port est accessible. Si vous vous connectez depuis l'extérieur du réseau local, assurez-vous que votre pare-feu autorise le trafic entrant sur le port API de sh0 (par défaut 9000).

HTTPS requis

Les clients MCP exigent généralement HTTPS pour les connexions distantes. Si vous accédez à sh0 via Internet, assurez-vous que votre serveur dispose d'un certificat SSL valide. Les connexions locales à localhost ou 127.0.0.1 peuvent fonctionner en HTTP simple.

Les outils n'apparaissent pas

Si la connexion réussit mais qu'aucun outil n'apparaît, la portée de la clé API est peut-être trop étroite pour les outils attendus. Vérifiez que la clé a la bonne portée dans Settings → API Keys. Vérifiez aussi que l'en-tête Authorization est correctement formaté en Bearer sh0_....

Session expirée

Les sessions expirent après 1 heure d'inactivité. Si vous recevez une erreur de session, le client devrait automatiquement se réinitialiser. Sinon, redémarrez le client MCP pour créer une nouvelle session.

Getting Started

AI Sandbox