Norsk English (UK) English (US) Svenska Deutsch Français Español 中文 (简体)

// GUIDES

Serveur MCP Isabyte

Serveur MCP Isabyte

Un serveur Model Context Protocol autonome qui fait de n'importe quel client d'IA compatible MCP un expert d'Isabyte Power Tools.

Le serveur MCP Isabyte embarque l'intégralité du corpus de compétences d'Isabyte Power Tools dans une image Linux légère (~50 Mo) et l'expose via le transport Streamable-HTTP du Model Context Protocol. Connectez Claude Desktop, Cline, Cursor, Continue ou tout autre client MCP, et votre assistant d'IA devient un spécialiste d'Isabyte, doté d'une connaissance fondée sur des sources de chaque composant, de chaque paramètre et de chaque modèle du catalogue.

Un serveur, un catalogue. Les fichiers de compétences décrivent le système de conception lui-même — le catalogue de composants, les paramètres et les variables de thème communs à tous les paquets Isabyte Power Tools : le même serveur alimente donc votre assistant, quel que soit le paquet avec lequel vous développez.

Lancer le serveur

  1. Téléchargez l'archive zip et décompressez-la.
  2. Chargez l'image dans votre moteur Docker local : bash load.sh
  3. Démarrez le serveur : docker run --rm -p 7180:7180 isabyte-mcp-server:<version>
  4. Vérifiez qu'il fonctionne : curl http://localhost:7180/health renvoie {"status":"ok","skills":10}.
  5. Connectez n'importe quel client MCP à http://localhost:7180/mcp.

Configuration du client MCP

Chaque client a son propre format de configuration, et une clé erronée conduit le client à ignorer l'entrée ou à se rabattre sur un ancien transport. La section Mettre en service le serveur MCP ci-dessous donne l'entrée exacte pour chaque client. La forme la plus courante est celle-ci, qu'utilise Cursor :

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Les autres clients diffèrent : VS Code utilise la clé servers avec "type": "http", Windsurf serverUrl, Gemini CLI httpUrl, Cline "type": "streamableHttp", et opencode une clé mcp avec "type": "remote". Claude Code et OpenAI Codex ajoutent le serveur au moyen d'une commande.

Une fois connecté, votre assistant peut lire chaque compétence Isabyte en tant que ressource MCP (isabyte-skill://) ou au moyen des outils MCP list_isabyte_skills et read_isabyte_skill, qui renvoient le même texte aux clients qui prennent en charge les outils mais pas les ressources. Le prompt isabyte_expert_guidance injecte toutes les compétences comme contexte de référence.

Sécurité

Par défaut, le serveur écoute sur 0.0.0.0 sans authentification — ce qui convient pour un seul poste de travail local. Si le conteneur est joignable au-delà de localhost :

  • Limitez l'écoute à localhost : -p 127.0.0.1:7180:7180
  • Ou exigez un jeton d'accès (bearer) : -e MCP_AUTH_TOKEN="$(openssl rand -hex 24)" et ajoutez "headers": { "Authorization": "Bearer YOUR_TOKEN" } à la configuration de votre client.

Mettre en service le serveur MCP

Un agent d'IA de programmation a besoin de deux éléments pour bien utiliser le serveur : une connexion (le serveur déclaré dans la configuration MCP de votre client) et un fichier d'instructions dans votre projet, qui lui indique quand s'en servir. Sans ce fichier, l'agent voit le serveur mais ignore qu'il doit consulter la documentation Isabyte avant d'écrire du code Isabyte ; il procède alors par supposition.

Le fichier d'instructions. Son contenu est identique pour tous les clients ; seuls le nom du fichier et son dossier changent, téléchargez donc ci-dessous celui de votre client. Il est rédigé en anglais à dessein : c'est l'agent qui le lit, pas votre équipe. Un téléchargement depuis le navigateur ne peut pas créer de dossiers ; déplacez donc le fichier vers le chemin indiqué pour votre client. Si votre projet contient déjà un fichier de ce nom, ajoutez le contenu à la fin de celui-ci au lieu de le remplacer. Les fichiers destinés à Cursor, Windsurf et Continue commencent par un court en-tête qui amène le client à charger le fichier à chaque session ; laissez-le tout en haut du fichier.

Avant de commencer. Le serveur doit être en cours d'exécution (voir Lancer le serveur). Tous les exemples ci-dessous l'enregistrent sous le nom isabyte-expert à l'adresse http://localhost:7180/mcp. Si vous avez démarré le serveur avec MCP_AUTH_TOKEN, ajoutez également l'en-tête Authorization: Bearer décrit dans Sécurité au champ des en-têtes de la configuration de votre client.

Ressources ou outils : les deux fonctionnent. Le serveur propose deux fois la documentation Isabyte, avec le même texte : sous forme de ressources MCP (isabyte-skill://…) et au moyen de deux outils MCP, list_isabyte_skills et read_isabyte_skill. Certains clients lisent les ressources, et tous les clients ci-dessous savent appeler des outils : l'agent dispose donc toujours d'un moyen de lire la documentation. Le fichier d'instructions lui indique d'utiliser l'outil lorsque son client ne sait pas lire les ressources.

Une requête de test valable pour tous les clients. Une fois le client connecté, ouvrez une nouvelle session dans votre projet et demandez : « Ajoutez un sélecteur de date Isabyte au formulaire d'inscription. » L'agent doit lire isabyte-skill://isabyte-controls.md, ou appeler read_isabyte_skill pour isabyte-controls, avant d'écrire la moindre ligne de code. S'il écrit du code Isabyte sans avoir d'abord lu la documentation Isabyte, c'est que le fichier d'instructions n'est pas chargé.

Claude Code

Configuration MCP — cette commande écrit .mcp.json à la racine du projet, si bien que toute personne qui ouvre le projet dispose du serveur :

claude mcp add --transport http --scope project isabyte-expert http://localhost:7180/mcp

Fichier d'instructions — CLAUDE.md à la racine du projet. Télécharger CLAUDE.md

Vérifier le fonctionnement — exécutez /mcp dans une session : isabyte-expert doit apparaître comme connecté. Essayez ensuite la requête de test.

Problèmes fréquents — au premier démarrage de Claude Code dans le projet, il vous demande d'approuver les serveurs déclarés dans .mcp.json ; si vous avez refusé, le serveur reste désactivé. Claude Code ne lit AGENTS.md que si le projet ne contient aucun fichier CLAUDE.md : placez donc le contenu dans CLAUDE.md.

OpenAI Codex

Configuration MCP — codex mcp add isabyte-expert --url http://localhost:7180/mcp, qui ajoute ceci à ~/.codex/config.toml :

[mcp_servers.isabyte-expert]
url = "http://localhost:7180/mcp"

Fichier d'instructions — AGENTS.md à la racine du projet. Télécharger AGENTS.md

Vérifier le fonctionnement — codex mcp list, ou /mcp dans l'interface en mode terminal de Codex. Essayez ensuite la requête de test.

Si vous avez démarré le serveur avec MCP_AUTH_TOKEN, placez le jeton dans une variable d'environnement et ajoutez bearer_token_env_var = "ISABYTE_TOKEN" (le nom de la variable) à l'entrée ; Codex l'envoie dans l'en-tête Authorization: Bearer.

Problèmes fréquents — un fichier .codex/config.toml propre au projet n'est lu que dans un projet que vous avez déclaré comme fiable. La documentation de Codex ne cite pas les ressources MCP : l'agent lit donc la documentation Isabyte au moyen des outils list_isabyte_skills et read_isabyte_skill. Si un long résultat d'outil est tronqué, augmentez output_token_limit pour read_isabyte_skill dans config.toml, ou demandez à l'agent de lire la compétence une section à la fois.

GitHub Copilot

Configuration MCP — dans VS Code, .vscode/mcp.json :

{
  "servers": {
    "isabyte-expert": {
      "type": "http",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Fichier d'instructions — .github/copilot-instructions.md. Télécharger copilot-instructions.md

Vérifier le fonctionnement — exécutez MCP: List Servers depuis la palette de commandes : isabyte-expert doit être en cours d'exécution, et MCP: Browse Resources liste ses ressources isabyte-skill://. Essayez la requête de test en mode agent.

Problèmes fréquents — ce fichier utilise la clé servers, et non mcpServers. L'agent cloud Copilot de GitHub.com s'exécute dans le cloud : il ne peut donc pas joindre un serveur situé sur votre localhost. Il n'utilise que les outils MCP, pas les ressources : avec un serveur qu'il peut joindre, il lit donc la documentation au moyen de list_isabyte_skills et read_isabyte_skill.

Cursor

Configuration MCP — .cursor/mcp.json dans le projet :

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Fichier d'instructions — .cursor/rules/isabyte-mcp.mdc. Télécharger isabyte-mcp.mdc

Vérifier le fonctionnement — la section MCP des paramètres de Cursor doit afficher isabyte-expert comme activé ; les erreurs de connexion figurent dans le panneau Output, sous « MCP Logs ». Essayez ensuite la requête de test.

Problèmes fréquents — une règle placée dans .cursor/rules/ doit porter l'extension .mdc ; un simple fichier .md y est ignoré. Cursor lit aussi un AGENTS.md situé à la racine du projet : si votre projet en contient déjà un, vous pouvez plutôt y ajouter le contenu.

Windsurf

Configuration MCP — ouvrez la section MCPs depuis le menu « … » de Cascade et modifiez directement la configuration (mcp_config.json) :

{
  "mcpServers": {
    "isabyte-expert": {
      "serverUrl": "http://localhost:7180/mcp"
    }
  }
}

Fichier d'instructions — .windsurf/rules/isabyte-mcp.md. Télécharger isabyte-mcp.md

Vérifier le fonctionnement — la section MCPs doit lister isabyte-expert avec ses outils et ses ressources. Essayez ensuite la requête de test dans Cascade.

Problèmes fréquents — Windsurf s'appelle désormais Devin Desktop. Il lit toujours .windsurf/rules/, mais son agent par défaut, Devin Local, lit les serveurs MCP dans .devin/mcp_config.json et non dans la configuration de Cascade ; ajoutez-y le serveur avec devin mcp add -s project isabyte-expert http://localhost:7180/mcp. Un fichier de règles ne peut pas dépasser 12 000 caractères.

Gemini CLI

Configuration MCP — cette commande écrit .gemini/settings.json dans le projet :

gemini mcp add --transport http isabyte-expert http://localhost:7180/mcp

L'entrée qu'elle écrit utilise httpUrl :

{
  "mcpServers": {
    "isabyte-expert": {
      "httpUrl": "http://localhost:7180/mcp"
    }
  }
}

Fichier d'instructions — GEMINI.md à la racine du projet. Télécharger GEMINI.md

Vérifier le fonctionnement — exécutez /mcp : isabyte-expert doit être connecté et ses outils et ressources listés. Essayez ensuite la requête de test.

Problèmes fréquents — dans settings.json, httpUrl désigne le transport Streamable-HTTP, celui qu'utilise ce serveur ; url désigne l'ancien transport SSE, avec lequel la connexion échoue. Gemini CLI ne lit AGENTS.md que si context.fileName le mentionne dans ses paramètres : utilisez donc GEMINI.md. Par défaut, Gemini CLI tronque les résultats d'outils de plus de 40 000 caractères (tools.truncateToolOutputThreshold) ; la plus longue compétence Isabyte dépasse cette taille, l'agent doit donc la lire une section à la fois (read_isabyte_skill accepte un paramètre section).

Cline

Configuration MCP — dans le panneau MCP Servers, choisissez Configure → « Configure MCP Servers » et ajoutez :

{
  "mcpServers": {
    "isabyte-expert": {
      "type": "streamableHttp",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Fichier d'instructions — .clinerules/isabyte-mcp.md. Télécharger isabyte-mcp.md

Vérifier le fonctionnement — le panneau MCP Servers doit afficher isabyte-expert comme connecté, avec les outils list_isabyte_skills et read_isabyte_skill. Essayez ensuite la requête de test.

Problèmes fréquents — sans "type": "streamableHttp", Cline se rabat sur l'ancien transport SSE et ne parvient pas à se connecter. La documentation de Cline ne mentionne les ressources MCP qu'en passant : l'agent lit donc la documentation Isabyte au moyen des outils.

Continue

Configuration MCP — un fichier .continue/mcpServers/isabyte-expert.yaml :

name: Isabyte MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: isabyte-expert
    type: streamable-http
    url: http://localhost:7180/mcp

Fichier d'instructions — .continue/rules/isabyte-mcp.md. Télécharger isabyte-mcp.md

Vérifier le fonctionnement — en mode agent, tapez @ : les ressources isabyte-expert doivent apparaître parmi les fournisseurs de contexte. Essayez ensuite la requête de test.

Problèmes fréquents — Continue n'utilise les serveurs MCP qu'en mode agent. Le fichier YAML doit comporter ses lignes name, version et schema, faute de quoi il n'est pas chargé. L'en-tête Authorization se place sous requestOptions: → headers: dans l'entrée du serveur.

opencode

Configuration MCP — opencode.json à la racine du projet :

{
  "mcp": {
    "isabyte-expert": {
      "type": "remote",
      "url": "http://localhost:7180/mcp",
      "enabled": true
    }
  }
}

Fichier d'instructions — AGENTS.md à la racine du projet, le même fichier que lit OpenAI Codex. Télécharger AGENTS.md

Vérifier le fonctionnement — opencode mcp list indique si isabyte-expert est connecté. Essayez ensuite la requête de test.

Problèmes fréquents — opencode ne lit CLAUDE.md que si le projet ne contient aucun fichier AGENTS.md. Sa documentation ne décrit que les outils MCP : l'agent lit donc la documentation Isabyte au moyen des outils list_isabyte_skills et read_isabyte_skill.

Claude Desktop

Claude Desktop ne prévoit pas de fichier d'instructions de projet. Dans un projet Claude, collez plutôt le contenu de l'un des fichiers téléchargeables ci-dessus dans les instructions du projet. Ses connecteurs personnalisés (Customize → Connectors → Add custom connector) se connectent depuis les serveurs d'Anthropic, et non depuis votre ordinateur ; ils ne peuvent donc pas joindre un serveur sur localhost : le serveur doit être accessible en HTTPS depuis Internet.

Si cela ne fonctionne toujours pas

  • curl http://localhost:7180/health échoue : le serveur n'est pas lancé.
  • L'adresse doit se terminer par /mcp.
  • Le client signale une erreur 401 : le serveur a été démarré avec MCP_AUTH_TOKEN, et le client n'envoie pas d'en-tête Authorization: Bearer, ou envoie un jeton erroné.
  • L'agent écrit du code Isabyte sans lire la documentation Isabyte (une ressource ou read_isabyte_skill) : le fichier d'instructions ne se trouve pas au chemin indiqué pour votre client, ou vous n'avez pas ouvert de nouvelle session depuis son ajout.
  • Après toute modification de la configuration MCP d'un client, redémarrez le client ou ouvrez une nouvelle session.
Une erreur non gérée s'est produite. Recharger 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.