Connecter votre agent

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.

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 :

"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client <name> [--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.

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 <fichier>.astral-backup-<timestamp>. 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
• Codex (CLI et IDE)
• VS Code et GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• Gemini CLI
• JetBrains AI Assistant
• Orca
• OpenCode
• Tout autre client MCP

Claude Code

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.

{
  "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

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.

Codex (CLI et IDE)

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.

[mcp_servers.astral]
command = "/Applications/Astral.app/Contents/MacOS/astral-mcp"
args = []

Source : Codex: MCP.

VS Code et GitHub Copilot

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.

{
  "servers": {
    "astral": {
      "type": "stdio",
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

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, VS Code: Add MCP servers.

Cursor

astral-mcp setup --client cursor

Écrit ~/.cursor/mcp.json. Avec --project, écrit .cursor/mcp.json.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Rechargez les serveurs MCP ou redémarrez Cursor pour qu’il le prenne en compte.

Source : Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Écrit ~/.codeium/windsurf/mcp_config.json. Windsurf n’a pas de configuration MCP par projet.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

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, VS Code: MCP configuration reference.

Antigravity

astral-mcp setup --client antigravity

Écrit ~/.gemini/config/mcp_config.json. Avec --project, écrit .agents/mcp_config.json.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Rechargez les serveurs MCP ou redémarrez Antigravity. Les anciennes installations utilisaient ~/.gemini/antigravity/mcp_config.json.

Source : Antigravity: MCP.

Gemini CLI

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.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Exécutez /mcp dans gemini pour le vérifier.

Source : Gemini CLI: MCP servers, Gemini CLI: configuration.

JetBrains AI Assistant

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).

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Source : JetBrains: AI Assistant MCP.

Orca

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 <worktree>.

# Settings → Integrations → MCP → command:
/Applications/Astral.app/Contents/MacOS/astral-mcp

Source : Orca docs.

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 :

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 :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "astral": {
        "type": "local",
        "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"]
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "astral": {
      "type": "local",
      "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"],
      "enabled": true
    }
  }
}

Source : OpenCode: MCP servers (V2) et la page de la V1. 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 :

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. 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.