Collega il tuo agente

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.

Il comando setup

Eseguilo con il percorso completo del binario (non è nel tuo PATH), oppure aggiungi quella cartella al 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

Negli esempi qui sotto si scrive astral-mcp per brevità.

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

Claude Code

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.

{
  "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 ti chiede di approvare un server di progetto da .mcp.json la prima volta che avvii claude lì.

Fonte: Claude Code: MCP.

Codex (CLI e IDE)

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.

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

Fonte: Codex: MCP.

VS Code e GitHub Copilot

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.

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

Avvia il server dal CodeLens sopra di esso nel file, oppure con il comando MCP: List Servers.

Fonte: VS Code: MCP configuration reference, VS Code: Add MCP servers.

Cursor

astral-mcp setup --client cursor

Scrive ~/.cursor/mcp.json. Con --project scrive .cursor/mcp.json.

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

Ricarica i server MCP o riavvia Cursor perché lo rilevi.

Fonte: Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Scrive ~/.codeium/windsurf/mcp_config.json. Windsurf non ha configurazione MCP per progetto.

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

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

Antigravity

astral-mcp setup --client antigravity

Scrive ~/.gemini/config/mcp_config.json. Con --project scrive .agents/mcp_config.json.

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

Ricarica i server MCP o riavvia Antigravity. Le installazioni più vecchie usavano ~/.gemini/antigravity/mcp_config.json.

Fonte: Antigravity: MCP.

Gemini CLI

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.

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

Esegui /mcp dentro gemini per verificarlo.

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

JetBrains AI Assistant

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

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

Fonte: JetBrains: AI Assistant MCP.

Orca

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

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

Fonte: Orca docs.

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:

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:

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

Fonte: OpenCode: MCP servers (V2) e la pagina della V1. 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:

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