# Collega il tuo agente > Fonte: https://astrallab.dev/it/docs/connect Il server MCP di Astral è locale: il tuo agente di programmazione avvia `astral-mcp`, che dialoga con l’app aperta. Tutti i client qui sotto hanno bisogno della stessa cosa, il percorso di quel binario. `astral-mcp setup` lo scrive per te. ## Prima di iniziare - **Astral è aperto, con Developer mode e MCP attivati** (Settings → Developer). L’agente dialoga con l’app in esecuzione; con Astral chiuso il bridge segnala un errore. - **Nessuna chiave API e nessuna variabile d’ambiente.** Il bridge si autentica a runtime con un token del socket locale. `setup` scrive solo il percorso del binario e un elenco `args` vuoto. - **Il binario è incluso nell’installer.** Su macOS è `/Applications/Astral.app/Contents/MacOS/astral-mcp`. La scheda **Connection** in Settings → Developer mostra il percorso esatto sulla tua macchina. I percorsi di installazione di Windows e Linux non sono documentati qui, e la build per Windows non è verificata su una macchina reale. - La modalità sviluppatore è testata su macOS e Linux (X11) e compilata ma non verificata su Windows; vedi [Piattaforme](https://astrallab.dev/it/docs/platforms.md). ## Il comando setup Eseguilo con il percorso completo del binario (non è nel tuo `PATH`), oppure aggiungi quella cartella al `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 ``` Negli esempi qui sotto si scrive `astral-mcp` per brevità. | Opzione | Effetto | | --- | --- | | `--client` | `claude-code`, `codex`, `vscode` (anche Copilot), `cursor`, `windsurf`, `antigravity`, `jetbrains`, `gemini-cli`, `orca` oppure `all-detected`. Se ne possono indicare più di uno separati da virgole. | | `--project [DIR]` | La configurazione del progetto (per impostazione predefinita, la directory corrente). | | `--global` | La configurazione dell’utente, per tutti i progetti. È l’impostazione predefinita quando il client ha un file globale documentato. | | `--print` | Mostra lo snippet e dove va; non scrive nulla. | | `--dry-run` | Mostra il diff; non scrive nulla. | | `--instructions` | Aggiunge anche la sezione di Astral all’`AGENTS.md` del progetto (`GEMINI.md` per Gemini CLI). | | `--binary PATH` | Registra quell’`astral-mcp` invece di quello in esecuzione. | | `--list` | Elenca i client, i loro file e se ciascuno è presente su questa macchina. | Setup unisce le modifiche nel file invece di sovrascriverlo: gli altri server e le altre chiavi vengono mantenuti, cambia solo la voce `astral`, un file che la contiene già corretta non viene toccato, e un file esistente viene prima copiato in `.astral-backup-`. Un file malformato viene segnalato con riga e colonna e non viene scritto nulla. `all-detected` è un’euristica: un client conta come installato se esiste la sua cartella di configurazione o se il suo comando è nel `PATH`. ## Per client - [Claude Code](#claude-code) - [Codex (CLI e IDE)](#codex) - [VS Code e GitHub Copilot](#vscode) - [Cursor](#cursor) - [Windsurf](#windsurf) - [Antigravity](#antigravity) - [Gemini CLI](#gemini-cli) - [JetBrains AI Assistant](#jetbrains) - [Orca](#orca) - [OpenCode](#opencode) - [Qualsiasi altro client MCP](#any) ### Claude Code ```bash astral-mcp setup --client claude-code --project . ``` Scrive .mcp.json nel progetto. Senza --project stampa il comando ufficiale per l’ambito utente invece di modificare ~/.claude.json, che Claude Code riscrive a ogni sessione. **Configurazione manuale: .mcp.json (progetto), oppure il comando qui sotto per ogni progetto** ``` { "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 ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Claude Code ti chiede di approvare un server di progetto da .mcp.json la prima volta che avvii claude lì. Fonte: [Claude Code: MCP](https://code.claude.com/docs/en/mcp). ### Codex (CLI e IDE) ```bash astral-mcp setup --client codex ``` Aggiunge \[mcp\_servers.astral\] a ~/.codex/config.toml (o $CODEX\_HOME/config.toml), mantenendo commenti e formattazione. Con --project scrive .codex/config.toml, che Codex legge solo nei progetti attendibili. **Configurazione manuale: ~/.codex/config.toml** ```toml [mcp_servers.astral] command = "/Applications/Astral.app/Contents/MacOS/astral-mcp" args = [] ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Fonte: [Codex: MCP](https://developers.openai.com/codex/mcp). ### VS Code e GitHub Copilot ```bash astral-mcp setup --client vscode --project . ``` Scrive .vscode/mcp.json, letto da VS Code e dalla modalità agente di Copilot. Senza --project scrive ~/.copilot/mcp-config.json (il file globale di Copilot, letto anche da GitHub Copilot CLI), che usa mcpServers invece di servers. **Configurazione manuale: .vscode/mcp.json** ```json { "servers": { "astral": { "type": "stdio", "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Avvia il server dal CodeLens sopra di esso nel file, oppure con il comando MCP: List Servers. Fonte: [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 ``` Scrive ~/.cursor/mcp.json. Con --project scrive .cursor/mcp.json. **Configurazione manuale: ~/.cursor/mcp.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Ricarica i server MCP o riavvia Cursor perché lo rilevi. Fonte: [Cursor: MCP](https://cursor.com/docs/mcp). ### Windsurf ```bash astral-mcp setup --client windsurf ``` Scrive ~/.codeium/windsurf/mcp\_config.json. Windsurf non ha configurazione MCP per progetto. **Configurazione manuale: ~/.codeium/windsurf/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Ricarica i server MCP o riavvia Windsurf. I canali next e insiders usano altre cartelle (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders) in cui setup non scrive. Fonte: [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 ``` Scrive ~/.gemini/config/mcp\_config.json. Con --project scrive .agents/mcp\_config.json. **Configurazione manuale: ~/.gemini/config/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Ricarica i server MCP o riavvia Antigravity. Le installazioni più vecchie usavano ~/.gemini/antigravity/mcp\_config.json. Fonte: [Antigravity: MCP](https://antigravity.google/docs/mcp). ### Gemini CLI ```bash astral-mcp setup --client gemini-cli ``` Unisce una voce mcpServers in ~/.gemini/settings.json e conserva il resto delle tue impostazioni. Con --project scrive .gemini/settings.json. **Configurazione manuale: ~/.gemini/settings.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Esegui /mcp dentro gemini per verificarlo. Fonte: [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 conserva i server MCP nelle impostazioni dell’IDE, non in un file documentato, quindi setup stampa il JSON invece di scriverlo. In Settings | Tools | AI Assistant | Model Context Protocol (MCP), scegli Add, poi JSON configuration, incollalo e scegli il livello del server (globale o questo progetto). **Configurazione manuale: impostazioni dell’IDE (nessun file)** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Fonte: [JetBrains: AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/mcp.html). ### Orca ```bash astral-mcp setup --client orca --print ``` Orca esegue altri agenti (Claude Code, Codex e così via) e inoltra loro i server MCP registrati in Settings → Integrations → MCP. Registra lì il percorso di astral-mcp, oppure configura l’agente che esegui dentro Orca, per esempio --client claude-code --project . **Configurazione manuale: impostazioni di Orca (nessun file)** ```json # Settings → Integrations → MCP → command: /Applications/Astral.app/Contents/MacOS/astral-mcp ``` Il percorso qui sopra è quello di macOS; usa il percorso di `astral-mcp` sulla tua macchina. Fonte: [Orca docs](https://www.onorca.dev/docs/cli/skills). ### OpenCode `astral-mcp setup` non supporta OpenCode, quindi configuralo a mano. La documentazione di OpenCode descrive un server locale come un comando che esso avvia tramite stdio. La sua documentazione più recente (V2) ne aggiunge uno dal terminale: ```bash opencode mcp add astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp opencode mcp list ``` Aggiungi `--global` per renderlo disponibile in ogni progetto; senza, il server va nella configurazione del progetto. A mano, in `opencode.jsonc`: **Configurazione manuale: opencode.jsonc (V2, documentazione più recente)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"] } } } } ``` **Configurazione manuale: opencode.jsonc (documentazione V1)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"], "enabled": true } } } ``` La V1 mette il server direttamente sotto `mcp`; la V2 lo mette sotto `mcp.servers`. Usa quella che corrisponde alla tua versione di OpenCode. Fonte: [OpenCode: MCP servers](https://opencode.ai/docs/mcp-servers/) (V2) e [la pagina della V1](https://opencode.ai/v1/docs/mcp-servers/). Non testato con un OpenCode in esecuzione. ### Qualsiasi altro client MCP Il server di Astral è un server MCP stdio standard. In qualsiasi client in grado di avviarne uno, registra: | Campo | Valore | | --- | --- | | Trasporto | stdio | | Comando | il percorso di `astral-mcp` (macOS: `/Applications/Astral.app/Contents/MacOS/astral-mcp`) | | Argomenti | nessuno | | Ambiente | nessuno | La maggior parte dei client lo accetta come JSON con un `command` e un elenco `args`, come negli snippet qui sopra. Controlla la pagina MCP del tuo client per il nome del file e la chiave di primo livello. ## Verifica che funzioni Con Astral aperto e la modalità sviluppatore attiva, riavvia o ricarica i server MCP dell’agente e chiedi: ``` Elenca gli strumenti che hai dal server MCP di Astral. ``` Dovresti vedere gli strumenti del [riferimento degli strumenti](https://astrallab.dev/it/docs/tools.md). Per una chiamata che tocchi l’app, chiedigli di eseguire `test_list` nel tuo progetto: restituisce i tuoi test salvati, oppure un elenco vuoto. In Gemini CLI, `/mcp` mostra il server e il suo stato. ### Se non compare - Assicurati che Astral sia in esecuzione e che Developer → MCP sia attivo, poi ricarica i server MCP del client. - Esegui `astral-mcp setup --list` per vedere dov’è il file di ciascun client e se è stato rilevato. - Esegui lo stesso comando con `--dry-run` per vedere cosa cambierebbe, o con `--print` per lo snippet. - Rieseguire setup è sicuro: non cambia nulla se la voce è già corretta. - Aggiungi `--instructions` perché l’agente riceva anche la breve guida all’uso di Astral in `AGENTS.md`.