Connecter le serveur MCP
Le serveur MCP d’Aggrega est la commande aggrega mcp, et le binaire aggrega est son seul prérequis : Installer le binaire l’installe en une seule commande. Le serveur s’exécute comme sous-processus de votre client via stdio, lit ses schémas dans le binaire et ses pages de documentation dans une copie qu’il télécharge une seule fois dans le cache de votre machine, et ne nécessite aucun service, port ou compte distinct. Si quelqu’un d’autre exécute déjà un serveur pour vous, vous n’avez besoin ni du binaire ni de rien de tout cela : voir Un serveur joint via HTTPS.
Clients qui l’ajoutent en une seule commande
Un assistant sur lequel le plugin Aggrega est installé est déjà connecté. L’installation du plugin ajoute la skill Aggrega et le serveur en une seule étape — dans Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro et OpenClaw, comme le décrit Installer le plugin —, si bien que rien d’autre sur cette page n’est nécessaire pour connecter cet assistant. Le plugin démarre aggrega mcp avec l’aggrega trouvé dans le PATH avec lequel l’assistant a été démarré ; le binaire doit donc y être installé. Certains assistants démarrent le serveur d’un plugin dans le propre dossier du plugin plutôt que dans votre projet — c’est le cas de Codex —, et l’assistant indique alors le dossier de votre projet comme workspace_root dans les appels qui l’acceptent ; la skill lui demande de vérifier dans quel espace de travail le serveur répond.
Sans le plugin, ajoutez le serveur avec la commande propre au client. Dans Claude Code :
claude mcp add --transport stdio aggrega -- aggrega mcpDans Codex :
codex mcp add aggrega -- aggrega mcpDans Gemini CLI :
gemini mcp add aggrega aggrega mcpTous les autres clients
La plupart des clients compatibles MCP lancent le serveur de la même façon — ils exécutent la commande aggrega avec un unique argument mcp et parlent le protocole sur l’entrée et la sortie standard du processus. Ce qui diffère entre eux, c’est où chacun conserve sa liste de serveurs et comment il en nomme les entrées. La forme commune :
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Une fois le client redémarré et connecté, les prompts, les ressources et les outils de rédaction d’Aggrega deviennent disponibles. Ce que votre assistant peut faire avec Aggrega les décrit, Rédiger des fichiers Aggrega montre quoi en faire, et la référence de aggrega mcp couvre la commande elle-même.
Rien dans l’entrée ne sélectionne une révision du protocole. Aggrega parle à la fois 2026-07-28 et 2025-06-18, sur l’entrée et la sortie standard comme via HTTPS, de sorte qu’un client de l’une ou l’autre se connecte et atteint les mêmes prompts, ressources et outils. Celle que demande un client se règle lors de l’échange plutôt que dans votre configuration.
Un assistant capable d’exécuter des commandes peut faire tout cela lui-même — installer le binaire, ajouter la skill Aggrega et se connecter au serveur — à partir d’un prompt unique que vous y collez : voir Configurer Aggrega avec votre assistant d’IA.
Où chaque client conserve sa liste de serveurs
| Client | Où se trouve la liste | Nom de l’entrée |
|---|---|---|
| Claude Code | claude mcp add, ou un fichier .mcp.json dans le projet | mcpServers |
| Claude Desktop | ses paramètres d’extensions pour un serveur local ; ses paramètres de connecteurs pour un serveur atteint via HTTPS | voir Claude Desktop |
| Cursor | .cursor/mcp.json pour un workspace, ou un mcp.json au niveau utilisateur pour tous les workspaces | mcpServers |
| Gemini CLI | gemini mcp add, ou ~/.gemini/settings.json pour tous les projets et .gemini/settings.json pour un seul | mcpServers |
| Codex CLI | codex mcp add, ou ~/.codex/config.toml pour tous les projets et .codex/config.toml pour un projet de confiance | une table [mcp_servers.aggrega] — voir Codex CLI |
| Zed | Settings → AI → MCP Servers, qui écrit l’entrée dans le fichier de paramètres de Zed | context_servers — voir Zed |
| Visual Studio Code | mcp.json dans votre profil utilisateur, ou .vscode/mcp.json pour un workspace | servers — voir Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, ou le fichier mcp-config.json qu’il conserve dans votre répertoire personnel | mcpServers |
| Antigravity | le fichier mcp_config.json accessible depuis ses paramètres | mcpServers |
| Windsurf | le fichier mcp_config.json accessible depuis ses paramètres | mcpServers |
| Cline | ses paramètres MCP, reposant sur un fichier cline_mcp_settings.json | mcpServers |
Chaque client de ce tableau, à l’exception des quatre qui ont leur propre section ci-dessous, accepte l’entrée exactement telle qu’écrite ci-dessus, au chemin indiqué sur sa ligne. Un client non listé se connecte de la même façon s’il lit une liste de serveurs de l’une de ces formes.
Une remarque sur PATH
Les clients lancés depuis un environnement graphique n’héritent pas toujours du même PATH que votre terminal. Si un client signale qu’il ne trouve pas la commande aggrega, remplacez "command": "aggrega" par le chemin absolu du binaire (par exemple "command": "/home/you/.local/bin/aggrega", l’emplacement d’installation sous Linux pour un utilisateur nommé you). Tout le reste est inchangé.
Visual Studio Code
Visual Studio Code conserve ses serveurs sous servers plutôt que mcpServers, et chaque entrée nomme le transport qu’elle utilise :
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex conserve ses serveurs en TOML plutôt qu’en JSON — dans ~/.codex/config.toml pour tous les projets, ou dans .codex/config.toml pour un projet auquel Codex fait confiance — chacun sous forme de table portant le nom du serveur :
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, la commande ci-dessus, écrit la même table pour vous. L’extension IDE de Codex et l’application de bureau ChatGPT lisent le même fichier, de sorte que l’unique entrée sert aux trois.
Zed
Zed conserve ses serveurs sous context_servers dans son fichier de paramètres. Ajoutez le serveur depuis Settings → AI → MCP Servers — Add Server, puis Add Local Server — ce qui écrit l’entrée dans ce fichier, ou lancez zed: open settings file depuis la palette de commandes et ajoutez l’entrée vous-même :
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed prend en charge les outils et les prompts du protocole, de sorte que son agent atteint les outils et les prompts de rédaction d’Aggrega, mais pas les ressources que le serveur propose également.
Claude Desktop
Claude Desktop installe un serveur local à partir d’un paquet d’extension — le serveur accompagné d’un manifest qui le décrit, regroupés en un seul fichier installable et ajoutés depuis ses paramètres d’extensions — plutôt qu’à partir d’une entrée dans un fichier de configuration. Chaque release d’Aggrega fournit un tel paquet, aggrega-<version>.mcpb, à côté de ses binaires précompilés.
Le paquet d’Aggrega ne contient aucun programme propre. Il lance un exécutable aggrega déjà installé sur votre machine, avec l’unique argument mcp, et parle le protocole sur l’entrée et la sortie standard de ce processus — le même serveur que lance chaque entrée ci-dessus. Sauf si vous choisissez un autre exécutable, il transmet à Claude Desktop le nom de commande aggrega, comme le fait chaque entrée ci-dessus, de sorte que l’application cherche aggrega dans le PATH avec lequel elle a été démarrée ; et il transmet à ce serveur le workspace que vous choisissez. Pour l’ajouter :
- Installez le binaire
aggrega, comme décrit dans Installer le binaire. La commande d’installation et les étapes manuelles décrites à cet endroit le placent toutes deux dans un dossier qui vous appartient — sous Windows%LOCALAPPDATA%\Programs\aggregaplutôt qu’un dossier système tel queC:\Windows\System32— afin que vous puissiez le remplacer sans droits d’administrateur. - Installez
aggrega-<version>.mcpbdepuis les paramètres d’extensions de Claude Desktop. - Définissez les paramètres du paquet ; aucun n’est obligatoire. Path to the aggrega executable est le programme que lance le paquet, et sa valeur par défaut est le nom de commande
aggrega, que l’application cherche dans lePATHavec lequel elle a été démarrée. Un dossier ajouté à votrePATHpendant que l’application s’exécute — comme le programme d’installation Windows et la commande d’installation sous Windows ajoutent le leur — ne lui parvient qu’une fois qu’elle a été quittée et redémarrée, comme à l’étape 4, et une application démarrée depuis un environnement graphique peut ne pas voir le mêmePATHque votre terminal (voir Une remarque surPATH). Conservez la valeur par défaut lorsque l’aggregade cePATHest l’exécutable voulu. Définissez plutôt le champ sur le chemin complet d’un exécutable lorsque celui que vous voulez n’est pas dans cePATH, ou est unaggregadifférent du premier qui y est trouvé — sous macOS et Linux, pour l’emplacement d’installation, l’aggregade.local/bindans votre dossier personnel, par exemple/Users/you/.local/bin/aggrega; sous Windows, le chemin complet se terminant paraggrega.exe, par exempleC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Pour revenir à la valeur par défaut, définissez le champ suraggregaplutôt que de le vider. Si aucunaggregan’est installé, installez-le comme le décrit l’étape 1. Workspace folder est le dossier du workspace Aggrega dans lequel travaille l’assistant : le dossier qui contient le.aggrega-config.yamlde votre projet. Définissez celui-ci : il est vide tant que vous n’avez pas choisi de dossier, et tant qu’il est vide, le paquet transmet au serveur unAGGREGA_WORKSPACE_ROOTvide, de sorte que le serveur répond à chaque requête que l’assistant fait dans le workspace par un refus indiquant que le paramètre Workspace folder est vide et vous invitant à le définir sur le dossier qui contient le.aggrega-config.yamlde votre workspace, plutôt que de travailler dans le dossier où Claude Desktop l’a démarré. Le paquet ne transmet le dossier au serveur qu’au moment où l’application démarre celui-ci ; un dossier que vous définissez pendant que le serveur s’exécute ne prend donc effet qu’une fois que vous avez désactivé puis réactivé l’extension dans les paramètres des extensions, ou redémarré l’application comme à l’étape 4. - Quittez complètement Claude Desktop, puis relancez-le. Un serveur que l’application a déjà démarré continue de s’exécuter, et renommer l’exécutable ne l’arrête pas ; un paramètre modifié ne prend donc effet qu’une fois que l’application redémarre le serveur : une fois qu’elle a été quittée et relancée ou, pour Workspace folder, une fois l’extension désactivée puis réactivée. Sous Windows, le Gestionnaire des tâches indique si un processus
aggregaest encore en cours d’exécution.
Le dossier du workspace est l’endroit où il est répondu à chaque requête qui ne nomme aucun workspace propre. Claude Desktop démarre le serveur dans un dossier de son choix plutôt que dans votre projet ; le paquet transmet donc le dossier que vous avez choisi au serveur sous la forme de la variable AGGREGA_WORKSPACE_ROOT dans son environnement, plutôt que sous la forme d’un argument sur la ligne de commande que compose l’application. Le serveur prend ce dossier comme racine du workspace elle-même, comme --workspace-root l’est sur chaque commande : il ne cherche pas au-dessus un workspace englobant ; choisissez donc le dossier qui contient .aggrega-config.yaml plutôt qu’un dossier à l’intérieur. Pour travailler dans un autre workspace, modifiez le paramètre et redémarrez l’application comme à l’étape 4. Pour une requête qui nomme son propre workspace avec un workspace_root relatif, celui-ci est lui aussi lu à partir du dossier du workspace, de sorte qu’un prompt nomme un dossier qu’il contient — par exemple quickstart-ai/1 — sans savoir où ce dossier se trouve sur votre machine ; un workspace_root absolu est utilisé tel quel. Tant que le paramètre est vide, un chemin relatif reçoit le même refus qu’une requête qui n’en nomme aucun.
Comme le paquet ne nomme aucun exécutable d’aucune plateforme, le même fichier s’applique à chaque plateforme qu’il déclare : macOS, Windows et Linux.
Le serveur indique quel aggrega le paquet a lancé. Les paramètres d’extensions de Claude Desktop affichent la version propre au paquet — la version de la release dont il provient — et non la version de l’exécutable qu’il lance. Les deux s’installent séparément et peuvent donc provenir de releases différentes. Le paquet transmet au serveur sa propre version sous la forme de la variable AGGREGA_BUNDLE_VERSION dans son environnement, et le serveur indique les deux : la réponse de describe-capabilities appelé sans argument — l’outil qu’un assistant appelle pour savoir ce que propose le serveur — commence par une ligne indiquant la version de l’exécutable et celle du paquet, et porte la même ligne sous version_summary dans sa partie structurée, de sorte qu’un assistant à qui l’on demande quelle version d’Aggrega s’exécute peut y lire les deux, quelle que soit la partie de la réponse que l’application lui transmet. Lorsque les deux proviennent de releases différentes, cette ligne le dit, en les nommant toutes les deux, et les indications que le serveur transmet à l’assistant à la connexion commencent par la même phrase. Rien n’est refusé en raison d’une différence, et le serveur répond à chaque requête comme d’habitude ; elle est signalée pour que vous sachiez quel exécutable le paquet exécute. Pour les aligner, installez l’aggrega-<version>.mcpb de la release dont provient votre exécutable — aggrega version dans un terminal affiche cette version — ou définissez Path to the aggrega executable sur le chemin complet d’un aggrega de la release du paquet, puis redémarrez l’application comme à l’étape 4.
Les journaux propres à Claude Desktop montrent ce qu’il a lancé. Sous Windows, ils peuvent se trouver sous un dossier de paquet dans le répertoire local des données d’application plutôt que sous %APPDATA%\Claude\logs, même lorsque Claude Desktop a été installé depuis son propre téléchargement : sous %LOCALAPPDATA%\Packages\, dans le dossier dont le nom commence par Claude_, dans LocalCache\Local\Claude\logs. Les fichiers qui s’y trouvent incluent mcp.log et mcp-server-Aggrega.log, le second contenant ce que le serveur Aggrega écrit sur sa sortie d’erreur standard. Une ligne contenant Using MCP server command: nomme la commande que l’application a lancée, tirée du paramètre Path to the aggrega executable du paquet. Lorsque le paramètre indique un chemin où rien ne se trouve, le journal contient le message de l’interpréteur de commandes de Windows indiquant que le chemin n’est pas reconnu comme une commande, puis signale que le serveur n’a pas pu démarrer. Lorsque le dossier du workspace n’existe pas — renommé, déplacé ou jamais créé —, le serveur démarre quand même et répond à chaque requête que l’assistant fait dans ce workspace par son refus, de sorte que l’assistant reçoit le refus comme réponse à sa requête au lieu que l’application signale un échec de connexion. Ce refus nomme AGGREGA_WORKSPACE_ROOT comme la variable que définit le paramètre Workspace folder du paquet, et cite le dossier exactement tel que l’application l’a transmis ; mcp-server-Aggrega.log contient le même refus. Un Workspace folder laissé vide reçoit la même réponse, avec le refus de l’étape 3 qui nomme le paramètre vide, et que le journal contient aussi. Corrigez le paramètre et redémarrez l’application comme à l’étape 4.
Les paramètres de connecteurs de Claude Desktop sont l’autre voie, pour un serveur atteint via HTTPS : voir Un serveur atteint via HTTPS.
Quand un client n’accepte pas l’ensemble des outils
Aggrega annonce l’ensemble de ses outils et laisse le client décider de la part qu’il présente au modèle. Certains clients plafonnent le nombre d’outils qu’ils enregistrent à la fois et abandonnent le reste. Dans ce cas, mcp.announce_tools réduit ce que le serveur annonce aux outils que vous nommez — voir Restreindre ce que le serveur annonce.
Un serveur atteint via HTTPS
Chaque entrée ci-dessus lance le serveur elle-même. Un serveur que quelqu’un d’autre exécute — un unique processus de longue durée sur un hôte, qui sert un workspace — est atteint par le réseau à la place, et son entrée nomme une adresse plutôt qu’une commande :
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}Le chemin est toujours /mcp ; l’hôte est celui que l’opérateur a publié pour ce serveur. Demandez-le-lui. Gemini CLI prend l’adresse sous httpUrl plutôt que url : il lit url comme un serveur utilisant l’ancien transport par flux d’événements, et httpUrl comme un serveur utilisant le transport HTTP streamable, qui est celui que parle ce serveur.
C’est votre client qui obtient le jeton, pas vous. Rien concernant la connexion n’est configuré dans l’entrée : le serveur répond à une requête non authentifiée en nommant le document qui indique quel serveur d’autorisation émet ses jetons, et un client qui parle le flux d’autorisation du protocole lit ce document, vous invite à vous connecter et joint le jeton qu’il reçoit à chaque requête ultérieure. Les noms des scopes qu’il peut demander sont publiés dans ce même document. Un client qui n’implémente pas ce flux ne peut pas atteindre un serveur de ce type, et rien de ce que vous ajoutez à l’entrée ne le remplace.
Un outil que les scopes de votre connexion n’atteignent pas figure malgré tout dans la liste des outils. Son appel est refusé, en nommant le scope qui l’autoriserait, et un client qui implémente le step-up du protocole répond à ce refus en vous demandant de vous reconnecter pour ce scope. Un client qui ne fait pas de step-up peut tout de même recevoir les scopes d’écriture : la personne qui gère le serveur d’autorisation en fait des scopes par défaut pour ce client, de sorte que sa première connexion les porte déjà — au prix que chaque connexion via ce client porte alors l’accès en écriture. Ce qu’un appelant peut atteindre expose ce que chaque scope autorise, et comment ce paramètre se comporte pour un client qui s’enregistre à nouveau à chaque connexion.
Ce qu’exige un tel serveur, et ce que son opérateur configure, est décrit dans la page aggrega mcp de la référence.
Vérifier la connexion
Une fois le client reconnecté, vérifiez que l’intégration est active : le client doit lister les prompts de rédaction d’Aggrega (un pour chacun des rôles développeur, architecte et exploitation, plus un modèle par entité) et les outils de rédaction — parmi lesquels scaffold, validate, describe et get-schema. Demandez à l’assistant de générer le squelette d’un composant ; il doit renvoyer un squelette contenant les champs qu’exige un Component. Si rien n’apparaît, vérifiez que aggrega version s’exécute depuis un terminal et que la command du client se résout vers le binaire — la remarque sur PATH ci-dessus couvre la cause habituelle.