Conecta tu agente

El servidor MCP de Astral es local: tu agente de programación arranca astral-mcp, que habla con la app abierta. Todos los clientes de abajo necesitan lo mismo: la ruta a ese binario. astral-mcp setup la escribe por ti.

Antes de empezar

• Astral está abierto, con el modo desarrollador y MCP activados (Ajustes → Desarrollador). El agente habla con la app en ejecución; con Astral cerrado, el puente informa de un error.
• Sin clave de API y sin variables de entorno. El puente se autentica en tiempo de ejecución con un token del socket local. setup solo escribe la ruta del binario y una lista args vacía.
• El binario viene dentro del instalador. En macOS es /Applications/Astral.app/Contents/MacOS/astral-mcp. La tarjeta Conexión de Ajustes → Desarrollador muestra la ruta exacta en tu equipo. Las rutas de instalación de Windows y Linux no se documentan aquí, y la versión de Windows no está verificada en una máquina real.
• El modo desarrollador está probado en macOS y Linux (X11), y compilado pero no verificado en Windows; consulta Plataformas.

El comando setup

Ejecútalo con la ruta completa del binario (no está en tu PATH), o añade esa carpeta 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

En los ejemplos de abajo se escribe astral-mcp para abreviar.

Setup fusiona los cambios en el archivo en lugar de sobrescribirlo: se conservan los demás servidores y claves, solo cambia la entrada astral, un archivo que ya la tiene correcta no se toca, y un archivo existente se copia antes a <archivo>.astral-backup-<timestamp>. Un archivo mal formado se notifica con su línea y columna y no se escribe nada. all-detected es una heurística: un cliente cuenta como instalado si existe su carpeta de configuración o su comando está en el PATH.

Por cliente

• Claude Code
• Codex (CLI e IDE)
• VS Code y GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• Gemini CLI
• JetBrains AI Assistant
• Orca
• OpenCode
• Cualquier otro cliente MCP

Claude Code

astral-mcp setup --client claude-code --project .

Escribe .mcp.json en el proyecto. Sin --project imprime el comando oficial para el ámbito de usuario en lugar de editar ~/.claude.json, que Claude Code reescribe en cada sesión.

{
  "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 te pide aprobar un servidor de proyecto de .mcp.json la primera vez que inicias claude allí.

Fuente: Claude Code: MCP.

Codex (CLI e IDE)

astral-mcp setup --client codex

Añade [mcp_servers.astral] a ~/.codex/config.toml (o $CODEX_HOME/config.toml), conservando comentarios y formato. Con --project escribe .codex/config.toml, que Codex solo lee en proyectos de confianza.

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

Fuente: Codex: MCP.

VS Code y GitHub Copilot

astral-mcp setup --client vscode --project .

Escribe .vscode/mcp.json, que leen VS Code y el modo agente de Copilot. Sin --project escribe ~/.copilot/mcp-config.json (el archivo global de Copilot, que también lee GitHub Copilot CLI), que usa mcpServers en lugar de servers.

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

Inicia el servidor desde el CodeLens que aparece sobre él en el archivo, o con el comando MCP: List Servers.

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

Cursor

astral-mcp setup --client cursor

Escribe ~/.cursor/mcp.json. Con --project escribe .cursor/mcp.json.

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

Recarga los servidores MCP o reinicia Cursor para que lo detecte.

Fuente: Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Escribe ~/.codeium/windsurf/mcp_config.json. Windsurf no tiene configuración MCP por proyecto.

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

Recarga los servidores MCP o reinicia Windsurf. Los canales next e insiders usan otras carpetas (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders) en las que setup no escribe.

Fuente: Devin CLI: configuration import, VS Code: MCP configuration reference.

Antigravity

astral-mcp setup --client antigravity

Escribe ~/.gemini/config/mcp_config.json. Con --project escribe .agents/mcp_config.json.

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

Recarga los servidores MCP o reinicia Antigravity. Las instalaciones antiguas usaban ~/.gemini/antigravity/mcp_config.json.

Fuente: Antigravity: MCP.

Gemini CLI

astral-mcp setup --client gemini-cli

Fusiona una entrada mcpServers en ~/.gemini/settings.json y conserva el resto de tus ajustes. Con --project escribe .gemini/settings.json.

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

Ejecuta /mcp dentro de gemini para comprobarlo.

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

JetBrains AI Assistant

astral-mcp setup --client jetbrains --print

JetBrains guarda los servidores MCP en los ajustes del IDE, no en un archivo documentado, así que setup imprime el JSON en lugar de escribirlo. En Settings | Tools | AI Assistant | Model Context Protocol (MCP), elige Add, luego JSON configuration, pégalo y elige el nivel del servidor (global o este proyecto).

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

Fuente: JetBrains: AI Assistant MCP.

Orca

astral-mcp setup --client orca --print

Orca ejecuta otros agentes (Claude Code, Codex, etc.) y les reenvía los servidores MCP registrados en Settings → Integrations → MCP. Registra allí la ruta de astral-mcp, o configura el agente que ejecutas dentro de Orca, por ejemplo --client claude-code --project <worktree>.

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

Fuente: Orca docs.

OpenCode

astral-mcp setup no admite OpenCode, así que configúralo a mano. La documentación de OpenCode describe un servidor local como un comando que él inicia por stdio. Su documentación más reciente (V2) añade uno desde la terminal:

opencode mcp add astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp
opencode mcp list

Añade --global para que esté disponible en todos los proyectos; sin él, el servidor se guarda en la configuración del proyecto. A mano, en 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
    }
  }
}

Fuente: OpenCode: MCP servers (V2) y la página de V1. No se ha probado con un OpenCode en ejecución.

Cualquier otro cliente MCP

El servidor de Astral es un servidor MCP stdio estándar. En cualquier cliente que pueda lanzar uno, registra:

La mayoría de los clientes lo aceptan como JSON con un command y una lista args, como en los fragmentos de arriba. Consulta la página MCP de tu cliente para el nombre del archivo y la clave de primer nivel.

Comprueba que funciona

Con Astral abierto y el modo desarrollador activado, reinicia o recarga los servidores MCP del agente y pregunta:

Enumera las herramientas que tienes del servidor MCP de Astral.

Deberías ver las herramientas de la referencia de herramientas. Para una llamada que toque la app, pídele que ejecute test_list en tu proyecto: devuelve tus pruebas guardadas, o una lista vacía. En Gemini CLI, /mcp muestra el servidor y su estado.

Si no aparece

• Comprueba que Astral está en ejecución y que Desarrollador → MCP está activado, y recarga los servidores MCP del cliente.
• Ejecuta astral-mcp setup --list para ver dónde está el archivo de cada cliente y si se detectó.
• Ejecuta el mismo comando con --dry-run para ver qué cambiaría, o con --print para ver el fragmento.
• Volver a ejecutar setup es seguro: no cambia nada si la entrada ya es correcta.
• Añade --instructions para que el agente reciba también la guía de uso breve de Astral en AGENTS.md.