# Connecter votre agent > Source : https://astrallab.dev/fr/docs/connect Le serveur MCP d’Astral est local : votre agent de programmation lance `astral-mcp`, qui dialogue avec l’application ouverte. Tous les clients ci-dessous ont besoin de la même chose, le chemin de ce binaire. `astral-mcp setup` l’écrit pour vous. ## Avant de commencer - **Astral est ouvert, avec le Developer mode et MCP activés** (Settings → Developer). L’agent dialogue avec l’application en cours d’exécution ; si Astral est fermé, le pont signale une erreur. - **Pas de clé d’API ni de variables d’environnement.** Le pont s’authentifie à l’exécution avec un jeton issu du socket local. `setup` n’écrit que le chemin du binaire et une liste `args` vide. - **Le binaire est inclus dans l’installateur.** Sur macOS, c’est `/Applications/Astral.app/Contents/MacOS/astral-mcp`. La carte **Connection** de Settings → Developer affiche le chemin exact sur votre machine. Les chemins d’installation de Windows et de Linux ne sont pas documentés ici, et la version Windows n’est pas vérifiée sur une machine réelle. - Le mode développeur est testé sur macOS et Linux (X11), et compilé mais non vérifié sur Windows ; voir [Plateformes](https://astrallab.dev/fr/docs/platforms.md). ## La commande setup Exécutez-la avec le chemin complet du binaire (il n’est pas dans votre `PATH`), ou ajoutez ce dossier au `PATH` : ```bash "/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client [--project [DIR] | --global] [--print] [--dry-run] [--instructions] [--binary PATH] "/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client all-detected --dry-run "/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --list ``` Les exemples ci-dessous écrivent `astral-mcp` par souci de concision. | Option | Effet | | --- | --- | | `--client` | `claude-code`, `codex`, `vscode` (aussi Copilot), `cursor`, `windsurf`, `antigravity`, `jetbrains`, `gemini-cli`, `orca` ou `all-detected`. Plusieurs valeurs peuvent être séparées par des virgules. | | `--project [DIR]` | La configuration du projet (le répertoire courant par défaut). | | `--global` | La configuration de l’utilisateur, pour tous les projets. C’est la valeur par défaut lorsque le client a un fichier global documenté. | | `--print` | Affiche l’extrait et son emplacement ; n’écrit rien. | | `--dry-run` | Affiche le diff ; n’écrit rien. | | `--instructions` | Ajoute aussi la section d’Astral à l’`AGENTS.md` du projet (`GEMINI.md` pour Gemini CLI). | | `--binary PATH` | Enregistre cet `astral-mcp` plutôt que celui en cours d’exécution. | | `--list` | Liste les clients, leurs fichiers et indique si chacun est présent sur cette machine. | Setup fusionne ses modifications dans le fichier au lieu de l’écraser : les autres serveurs et clés sont conservés, seule l’entrée `astral` change, un fichier qui la contient déjà correctement n’est pas touché, et un fichier existant est d’abord copié vers `.astral-backup-`. Un fichier mal formé est signalé avec sa ligne et sa colonne, et rien n’est écrit. `all-detected` est une heuristique : un client compte comme installé si son dossier de configuration existe ou si sa commande se trouve dans le `PATH`. ## Par client - [Claude Code](#claude-code) - [Codex (CLI et IDE)](#codex) - [VS Code et GitHub Copilot](#vscode) - [Cursor](#cursor) - [Windsurf](#windsurf) - [Antigravity](#antigravity) - [Gemini CLI](#gemini-cli) - [JetBrains AI Assistant](#jetbrains) - [Orca](#orca) - [OpenCode](#opencode) - [Tout autre client MCP](#any) ### Claude Code ```bash astral-mcp setup --client claude-code --project . ``` Écrit .mcp.json dans le projet. Sans --project, affiche la commande officielle pour la portée utilisateur au lieu de modifier ~/.claude.json, que Claude Code réécrit à chaque session. **Configuration manuelle : .mcp.json (projet), ou la commande ci-dessous pour tous les projets** ``` { "mcpServers": { "astral": { "type": "stdio", "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } # user scope, every project: claude mcp add --scope user astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Claude Code vous demande d’approuver un serveur de projet issu de .mcp.json la première fois que vous lancez claude à cet endroit. Source : [Claude Code: MCP](https://code.claude.com/docs/en/mcp). ### Codex (CLI et IDE) ```bash astral-mcp setup --client codex ``` Ajoute \[mcp\_servers.astral\] à ~/.codex/config.toml (ou $CODEX\_HOME/config.toml), en conservant les commentaires et la mise en forme. Avec --project, écrit .codex/config.toml, que Codex ne lit que dans les projets de confiance. **Configuration manuelle : ~/.codex/config.toml** ```toml [mcp_servers.astral] command = "/Applications/Astral.app/Contents/MacOS/astral-mcp" args = [] ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Source : [Codex: MCP](https://developers.openai.com/codex/mcp). ### VS Code et GitHub Copilot ```bash astral-mcp setup --client vscode --project . ``` Écrit .vscode/mcp.json, lu par VS Code et par le mode agent de Copilot. Sans --project, écrit ~/.copilot/mcp-config.json (le fichier global de Copilot, également lu par GitHub Copilot CLI), qui utilise mcpServers au lieu de servers. **Configuration manuelle : .vscode/mcp.json** ```json { "servers": { "astral": { "type": "stdio", "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Démarrez le serveur depuis le CodeLens au-dessus de lui dans le fichier, ou avec la commande MCP: List Servers. Source : [VS Code: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration), [VS Code: Add MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers). ### Cursor ```bash astral-mcp setup --client cursor ``` Écrit ~/.cursor/mcp.json. Avec --project, écrit .cursor/mcp.json. **Configuration manuelle : ~/.cursor/mcp.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Rechargez les serveurs MCP ou redémarrez Cursor pour qu’il le prenne en compte. Source : [Cursor: MCP](https://cursor.com/docs/mcp). ### Windsurf ```bash astral-mcp setup --client windsurf ``` Écrit ~/.codeium/windsurf/mcp\_config.json. Windsurf n’a pas de configuration MCP par projet. **Configuration manuelle : ~/.codeium/windsurf/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Rechargez les serveurs MCP ou redémarrez Windsurf. Les canaux next et insiders utilisent d’autres dossiers (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders) dans lesquels setup n’écrit pas. Source : [Devin CLI: configuration import](https://docs.devin.ai/cli/reference/configuration/read-config-from), [VS Code: MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Antigravity ```bash astral-mcp setup --client antigravity ``` Écrit ~/.gemini/config/mcp\_config.json. Avec --project, écrit .agents/mcp\_config.json. **Configuration manuelle : ~/.gemini/config/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Rechargez les serveurs MCP ou redémarrez Antigravity. Les anciennes installations utilisaient ~/.gemini/antigravity/mcp\_config.json. Source : [Antigravity: MCP](https://antigravity.google/docs/mcp). ### Gemini CLI ```bash astral-mcp setup --client gemini-cli ``` Fusionne une entrée mcpServers dans ~/.gemini/settings.json et conserve le reste de vos paramètres. Avec --project, écrit .gemini/settings.json. **Configuration manuelle : ~/.gemini/settings.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Exécutez /mcp dans gemini pour le vérifier. Source : [Gemini CLI: MCP servers](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md), [Gemini CLI: configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md). ### JetBrains AI Assistant ```bash astral-mcp setup --client jetbrains --print ``` JetBrains conserve les serveurs MCP dans les paramètres de l’IDE, et non dans un fichier documenté ; setup affiche donc le JSON au lieu de l’écrire. Dans Settings | Tools | AI Assistant | Model Context Protocol (MCP), choisissez Add, puis JSON configuration, collez-le et choisissez le niveau du serveur (global ou ce projet). **Configuration manuelle : paramètres de l’IDE (pas de fichier)** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Source : [JetBrains: AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/mcp.html). ### Orca ```bash astral-mcp setup --client orca --print ``` Orca exécute d’autres agents (Claude Code, Codex, etc.) et leur transmet les serveurs MCP enregistrés dans Settings → Integrations → MCP. Enregistrez-y le chemin d’astral-mcp, ou configurez l’agent que vous exécutez dans Orca, par exemple --client claude-code --project . **Configuration manuelle : paramètres d’Orca (pas de fichier)** ```json # Settings → Integrations → MCP → command: /Applications/Astral.app/Contents/MacOS/astral-mcp ``` Le chemin ci-dessus est celui de macOS ; utilisez le chemin d’`astral-mcp` sur votre machine. Source : [Orca docs](https://www.onorca.dev/docs/cli/skills). ### OpenCode `astral-mcp setup` ne prend pas en charge OpenCode ; configurez-le donc à la main. La documentation d’OpenCode décrit un serveur local comme une commande qu’il lance via stdio. Sa documentation la plus récente (V2) en ajoute un depuis le terminal : ```bash opencode mcp add astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp opencode mcp list ``` Ajoutez `--global` pour le rendre disponible dans tous les projets ; sans cette option, le serveur est placé dans la configuration du projet. À la main, dans `opencode.jsonc` : **Configuration manuelle : opencode.jsonc (V2, documentation la plus récente)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"] } } } } ``` **Configuration manuelle : opencode.jsonc (documentation V1)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"], "enabled": true } } } ``` La V1 place le serveur directement sous `mcp` ; la V2 le place sous `mcp.servers`. Utilisez celle qui correspond à votre version d’OpenCode. Source : [OpenCode: MCP servers](https://opencode.ai/docs/mcp-servers/) (V2) et [la page de la V1](https://opencode.ai/v1/docs/mcp-servers/). Non testé avec un OpenCode en cours d’exécution. ### Tout autre client MCP Le serveur d’Astral est un serveur MCP stdio standard. Dans tout client capable d’en lancer un, enregistrez : | Champ | Valeur | | --- | --- | | Transport | stdio | | Commande | le chemin d’`astral-mcp` (macOS : `/Applications/Astral.app/Contents/MacOS/astral-mcp`) | | Arguments | aucun | | Environnement | aucun | La plupart des clients acceptent cela sous forme de JSON avec un `command` et une liste `args`, comme dans les extraits ci-dessus. Consultez la page MCP de votre client pour le nom du fichier et la clé de premier niveau. ## Vérifier que cela fonctionne Avec Astral ouvert et le mode développeur activé, redémarrez ou rechargez les serveurs MCP de l’agent et demandez : ``` Liste les outils dont tu disposes depuis le serveur MCP d’Astral. ``` Vous devriez voir les outils de la [référence des outils](https://astrallab.dev/fr/docs/tools.md). Pour un appel qui touche l’application, demandez-lui d’exécuter `test_list` dans votre projet : il renvoie vos tests enregistrés, ou une liste vide. Dans Gemini CLI, `/mcp` affiche le serveur et son état. ### S’il n’apparaît pas - Vérifiez qu’Astral est en cours d’exécution et que Developer → MCP est activé, puis rechargez les serveurs MCP du client. - Exécutez `astral-mcp setup --list` pour voir où se trouve le fichier de chaque client et s’il a été détecté. - Exécutez la même commande avec `--dry-run` pour voir ce qui changerait, ou avec `--print` pour obtenir l’extrait. - Relancer setup est sans risque : rien ne change si l’entrée est déjà correcte. - Ajoutez `--instructions` pour que l’agent reçoive aussi le court guide d’utilisation d’Astral dans `AGENTS.md`.