# Conecta tu agente > Fuente: https://astrallab.dev/es/docs/connect 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](https://astrallab.dev/es/docs/platforms.md). ## El comando setup Ejecútalo con la ruta completa del binario (no está en tu `PATH`), o añade esa carpeta 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 ``` En los ejemplos de abajo se escribe `astral-mcp` para abreviar. | Opción | Efecto | | --- | --- | | `--client` | `claude-code`, `codex`, `vscode` (también Copilot), `cursor`, `windsurf`, `antigravity`, `jetbrains`, `gemini-cli`, `orca` o `all-detected`. Se pueden indicar varios separados por comas. | | `--project [DIR]` | La configuración del proyecto (por defecto, el directorio actual). | | `--global` | La configuración del usuario, para todos los proyectos. Es la opción por defecto cuando el cliente tiene un archivo global documentado. | | `--print` | Muestra el fragmento y dónde va; no escribe nada. | | `--dry-run` | Muestra el diff; no escribe nada. | | `--instructions` | Añade además la sección de Astral al `AGENTS.md` del proyecto (`GEMINI.md` para Gemini CLI). | | `--binary PATH` | Registra ese `astral-mcp` en lugar del que se está ejecutando. | | `--list` | Lista los clientes, sus archivos y si cada uno se encuentra en este equipo. | 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 `.astral-backup-`. 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](#claude-code) - [Codex (CLI e IDE)](#codex) - [VS Code y GitHub Copilot](#vscode) - [Cursor](#cursor) - [Windsurf](#windsurf) - [Antigravity](#antigravity) - [Gemini CLI](#gemini-cli) - [JetBrains AI Assistant](#jetbrains) - [Orca](#orca) - [OpenCode](#opencode) - [Cualquier otro cliente MCP](#any) ### Claude Code ```bash 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. **Configuración manual: .mcp.json (proyecto), o el comando de abajo para todos los proyectos** ``` { "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 ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Claude Code te pide aprobar un servidor de proyecto de .mcp.json la primera vez que inicias claude allí. Fuente: [Claude Code: MCP](https://code.claude.com/docs/en/mcp). ### Codex (CLI e IDE) ```bash 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. **Configuración manual: ~/.codex/config.toml** ```toml [mcp_servers.astral] command = "/Applications/Astral.app/Contents/MacOS/astral-mcp" args = [] ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Fuente: [Codex: MCP](https://developers.openai.com/codex/mcp). ### VS Code y GitHub Copilot ```bash 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. **Configuración manual: .vscode/mcp.json** ```json { "servers": { "astral": { "type": "stdio", "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. 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](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 ``` Escribe ~/.cursor/mcp.json. Con --project escribe .cursor/mcp.json. **Configuración manual: ~/.cursor/mcp.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Recarga los servidores MCP o reinicia Cursor para que lo detecte. Fuente: [Cursor: MCP](https://cursor.com/docs/mcp). ### Windsurf ```bash astral-mcp setup --client windsurf ``` Escribe ~/.codeium/windsurf/mcp\_config.json. Windsurf no tiene configuración MCP por proyecto. **Configuración manual: ~/.codeium/windsurf/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. 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](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 ``` Escribe ~/.gemini/config/mcp\_config.json. Con --project escribe .agents/mcp\_config.json. **Configuración manual: ~/.gemini/config/mcp\_config.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Recarga los servidores MCP o reinicia Antigravity. Las instalaciones antiguas usaban ~/.gemini/antigravity/mcp\_config.json. Fuente: [Antigravity: MCP](https://antigravity.google/docs/mcp). ### Gemini CLI ```bash 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. **Configuración manual: ~/.gemini/settings.json** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Ejecuta /mcp dentro de gemini para comprobarlo. Fuente: [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 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). **Configuración manual: ajustes del IDE (sin archivo)** ```json { "mcpServers": { "astral": { "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp", "args": [] } } } ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Fuente: [JetBrains: AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/mcp.html). ### Orca ```bash 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 . **Configuración manual: ajustes de Orca (sin archivo)** ```json # Settings → Integrations → MCP → command: /Applications/Astral.app/Contents/MacOS/astral-mcp ``` La ruta de arriba es la de macOS; usa la ruta de `astral-mcp` en tu equipo. Fuente: [Orca docs](https://www.onorca.dev/docs/cli/skills). ### 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: ```bash 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`: **Configuración manual: opencode.jsonc (V2, documentación más reciente)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"] } } } } ``` **Configuración manual: opencode.jsonc (documentación V1)** ```jsonc { "$schema": "https://opencode.ai/config.json", "mcp": { "astral": { "type": "local", "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"], "enabled": true } } } ``` V1 coloca el servidor directamente bajo `mcp`; V2 lo coloca bajo `mcp.servers`. Usa el que corresponda a tu versión de OpenCode. Fuente: [OpenCode: MCP servers](https://opencode.ai/docs/mcp-servers/) (V2) y [la página de V1](https://opencode.ai/v1/docs/mcp-servers/). 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: | Campo | Valor | | --- | --- | | Transporte | stdio | | Comando | la ruta de `astral-mcp` (macOS: `/Applications/Astral.app/Contents/MacOS/astral-mcp`) | | Argumentos | ninguno | | Entorno | ninguno | 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](https://astrallab.dev/es/docs/tools.md). 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`.