Conectar el servidor MCP
El servidor MCP de Aggrega es el comando aggrega mcp, y el binario aggrega es su único requisito previo: Instalar el binario lo instala con un solo comando. El servidor se ejecuta como subproceso de tu cliente a través de stdio, lee sus esquemas del binario y sus páginas de documentación de una copia que descarga una sola vez en la caché de tu máquina, y no necesita ningún servicio, puerto ni cuenta aparte. Si otra persona ya ejecuta un servidor para ti, no necesitas ni el binario ni nada de esto: consulta Un servidor al que se accede por HTTPS.
Clientes que lo añaden con un solo comando
Un asistente con el plugin de Aggrega instalado ya está conectado. Instalar el plugin añade la skill de Aggrega y el servidor en un solo paso —en Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro y OpenClaw, como describe Instalar el plugin—, así que no se necesita nada más de esta página para conectar ese asistente. El plugin inicia aggrega mcp con el aggrega que encuentra en el PATH con el que se inició el asistente, así que el binario debe estar instalado ahí. Algunos asistentes inician el servidor de un plugin en la carpeta propia del plugin en lugar de en tu proyecto —Codex lo hace—, y entonces el asistente indica la carpeta de tu proyecto como workspace_root en las llamadas que lo admiten; la skill le indica que compruebe en qué espacio de trabajo responde el servidor.
Sin el plugin, añade el servidor con el comando propio del cliente. En Claude Code:
claude mcp add --transport stdio aggrega -- aggrega mcpEn Codex:
codex mcp add aggrega -- aggrega mcpEn Gemini CLI:
gemini mcp add aggrega aggrega mcpCualquier otro cliente
La mayoría de los clientes compatibles con MCP inician el servidor del mismo modo — ejecutan el comando aggrega con un único argumento mcp y hablan el protocolo por la entrada y la salida estándar del proceso. Lo que cambia entre ellos es dónde guarda cada uno su lista de servidores y cómo llama a sus entradas. La forma común:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Una vez que el cliente se reinicia y se conecta, quedan disponibles los prompts, los recursos y las herramientas de redacción de Aggrega. Qué puede hacer tu asistente con Aggrega los describe, Redactar archivos de Aggrega muestra qué hacer con ellos, y la referencia de aggrega mcp trata el propio comando.
Nada en la entrada selecciona una revisión del protocolo. Aggrega habla tanto 2026-07-28 como 2025-06-18, por la entrada y la salida estándar igual que por HTTPS, de modo que un cliente de cualquiera de las dos se conecta y llega a los mismos prompts, recursos y herramientas. Cuál pide un cliente se decide en la comunicación y no en tu configuración.
Un asistente capaz de ejecutar comandos puede hacer todo esto por sí mismo — instalar el binario, añadir la skill de Aggrega y conectarse al servidor — a partir de un único prompt que pegas en él: consulta Configurar Aggrega con tu asistente de IA.
Dónde guarda cada cliente su lista de servidores
| Cliente | Dónde está la lista | Cómo se llama la entrada |
|---|---|---|
| Claude Code | claude mcp add, o un archivo .mcp.json en el proyecto | mcpServers |
| Claude Desktop | su configuración de extensiones para un servidor local; su configuración de conectores para uno al que se accede por HTTPS | consulta Claude Desktop |
| Cursor | .cursor/mcp.json para un workspace, o un mcp.json de ámbito de usuario para todos los workspaces | mcpServers |
| Gemini CLI | gemini mcp add, o ~/.gemini/settings.json para todos los proyectos y .gemini/settings.json para uno | mcpServers |
| Codex CLI | codex mcp add, o ~/.codex/config.toml para todos los proyectos y .codex/config.toml para un proyecto de confianza | una tabla [mcp_servers.aggrega] — consulta Codex CLI |
| Zed | Settings → AI → MCP Servers, que escribe la entrada en el archivo de ajustes de Zed | context_servers — consulta Zed |
| Visual Studio Code | mcp.json en tu perfil de usuario, o .vscode/mcp.json para un workspace | servers — consulta Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, o el archivo mcp-config.json que guarda en tu directorio personal | mcpServers |
| Antigravity | el archivo mcp_config.json accesible desde su configuración | mcpServers |
| Windsurf | el archivo mcp_config.json accesible desde su configuración | mcpServers |
| Cline | su configuración de MCP, respaldada por un archivo cline_mcp_settings.json | mcpServers |
Todos los clientes de esa tabla, excepto los cuatro que tienen su propia sección más abajo, aceptan la entrada exactamente como está escrita arriba, en la ruta de su fila. Un cliente no incluido se conecta del mismo modo si lee una lista de servidores de una de estas formas.
Una nota sobre PATH
Los clientes iniciados desde un entorno gráfico no siempre heredan el mismo PATH que tu terminal. Si un cliente indica que no encuentra el comando aggrega, sustituye "command": "aggrega" por la ruta absoluta al binario (por ejemplo "command": "/home/you/.local/bin/aggrega", la ubicación de instalación en Linux para un usuario llamado you). Todo lo demás sigue igual.
Visual Studio Code
Visual Studio Code guarda sus servidores en servers en lugar de mcpServers, y cada entrada nombra el transporte que usa:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex guarda sus servidores en TOML en lugar de JSON — en ~/.codex/config.toml para todos los proyectos, o en .codex/config.toml para un proyecto en el que Codex confía — cada uno como una tabla con el nombre del servidor:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, el comando de más arriba, escribe la misma tabla por ti. La extensión de IDE de Codex y la aplicación de escritorio de ChatGPT leen el mismo archivo, así que la única entrada sirve a las tres.
Zed
Zed guarda sus servidores bajo context_servers en su archivo de ajustes. Añade el servidor desde Settings → AI → MCP Servers — Add Server y luego Add Local Server — lo que escribe la entrada en ese archivo, o ejecuta zed: open settings file desde la paleta de comandos y añade tú mismo la entrada:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed admite las herramientas y los prompts del protocolo, así que su agente llega a las herramientas y los prompts de redacción de Aggrega, pero no a los recursos que el servidor también ofrece.
Claude Desktop
Claude Desktop instala un servidor local a partir de un paquete de extensión — el servidor junto con un manifiesto que lo describe, empaquetados en un único archivo instalable y añadidos desde su configuración de extensiones — en lugar de a partir de una entrada en un archivo de configuración. Cada release de Aggrega incluye un paquete así, aggrega-<version>.mcpb, junto a sus binarios precompilados.
El paquete de Aggrega no contiene ningún programa propio. Inicia un ejecutable aggrega ya instalado en tu máquina, con el único argumento mcp, y habla el protocolo por la entrada y la salida estándar de ese proceso — el mismo servidor que inicia cada entrada anterior. A menos que elijas otro ejecutable, entrega a Claude Desktop el nombre de comando aggrega, como hace cada entrada anterior, de modo que la aplicación busca aggrega en el PATH con el que se inició; y entrega a ese servidor el workspace que elijas. Para añadirlo:
- Instala el binario
aggrega, como se describe en Instalar el binario. Tanto el comando de instalación como los pasos manuales que allí se indican lo guardan en una carpeta tuya — en Windows%LOCALAPPDATA%\Programs\aggregaen lugar de una carpeta del sistema comoC:\Windows\System32— para que puedas sustituirlo sin derechos de administrador. - Instala
aggrega-<version>.mcpbdesde la configuración de extensiones de Claude Desktop. - Define los ajustes del paquete; ninguno es obligatorio. Path to the aggrega executable es el programa que inicia el paquete, y su valor predeterminado es el nombre de comando
aggrega, que la aplicación busca en elPATHcon el que se inició. Una carpeta añadida a tuPATHmientras la aplicación se ejecuta — como añaden la suya el instalador de Windows y el comando de instalación en Windows — solo le llega una vez que se ha cerrado y vuelto a iniciar, como en el paso 4, y una aplicación iniciada desde un entorno gráfico puede no ver el mismoPATHque tu terminal (consulta Una nota sobrePATH). Deja el valor predeterminado cuando elaggregade esePATHsea el ejecutable que quieres. Establece en cambio el campo en la ruta completa de un ejecutable cuando el que quieres no esté en esePATH, o sea unaggregadistinto del primero que se encuentra allí — en macOS y Linux, para la ubicación de instalación, elaggregade.local/binen tu carpeta personal, como/Users/you/.local/bin/aggrega; en Windows, la ruta completa que termina enaggrega.exe, comoC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Para volver al valor predeterminado, establece el campo enaggregaen lugar de vaciarlo. Si no hay ningúnaggregainstalado, instálalo como describe el paso 1. Workspace folder es la carpeta del workspace de Aggrega en la que trabaja el asistente: la carpeta que contiene el.aggrega-config.yamlde tu proyecto. Define este: está vacío hasta que eliges una carpeta, y mientras está vacío el paquete entrega al servidor unAGGREGA_WORKSPACE_ROOTvacío, de modo que el servidor responde a cada solicitud que el asistente hace en el workspace con un rechazo que indica que el ajuste Workspace folder está vacío y te pide que lo establezcas en la carpeta que contiene el.aggrega-config.yamlde tu workspace, en lugar de trabajar en la carpeta en la que Claude Desktop lo inició. El paquete entrega la carpeta al servidor solo cuando la aplicación lo inicia, así que una carpeta que defines mientras el servidor se ejecuta surte efecto una vez que desactivas y vuelves a activar la extensión en los ajustes de extensiones, o reinicias la aplicación como en el paso 4. - Cierra Claude Desktop por completo y vuelve a iniciarlo. Un servidor que la aplicación ya ha iniciado sigue ejecutándose, y cambiar el nombre del ejecutable no lo detiene, así que un ajuste modificado solo surte efecto una vez que la aplicación vuelve a iniciar el servidor: una vez que se ha cerrado y vuelto a iniciar o, para Workspace folder, una vez que la extensión se desactiva y se vuelve a activar. En Windows, el Administrador de tareas muestra si un proceso
aggregasigue en ejecución.
La carpeta del workspace es donde se responde a cada solicitud que no nombra un workspace propio. Claude Desktop inicia el servidor en una carpeta elegida por él en lugar de en tu proyecto, por lo que el paquete pasa al servidor la carpeta que elegiste como la variable AGGREGA_WORKSPACE_ROOT de su entorno, en lugar de como un argumento en la línea de comandos que compone la aplicación. El servidor toma esa carpeta como la raíz del workspace misma, igual que se toma --workspace-root en cada comando: no busca por encima de ella un workspace que la contenga, así que elige la carpeta que contiene .aggrega-config.yaml y no una dentro de ella. Para trabajar en otro workspace, cambia el ajuste y reinicia la aplicación como en el paso 4. En una solicitud que nombra un workspace propio con un workspace_root relativo, este también se lee a partir de la carpeta del workspace, de modo que un prompt nombra una carpeta dentro de ella —como quickstart-ai/1— sin saber dónde está la carpeta en tu máquina; un workspace_root absoluto se usa tal como se da. Mientras el ajuste está vacío, uno relativo recibe el mismo rechazo que una solicitud que no nombra ninguno.
Como el paquete no nombra ningún ejecutable de ninguna plataforma, el mismo archivo sirve para cada plataforma que declara: macOS, Windows y Linux.
El servidor informa de qué aggrega inició el paquete. La configuración de extensiones de Claude Desktop muestra la versión del propio paquete — la versión de la release de la que procede — y no la versión del ejecutable que el paquete inicia. Ambos se instalan por separado, por lo que pueden proceder de releases distintas. El paquete entrega al servidor su propia versión como la variable AGGREGA_BUNDLE_VERSION de su entorno, y el servidor informa de ambas: la respuesta de describe-capabilities llamado sin argumentos — la herramienta a la que llama un asistente para saber qué ofrece el servidor — comienza con una línea que nombra la versión del ejecutable y la del paquete, y lleva la misma línea como version_summary en su parte estructurada, de modo que un asistente al que se le pregunta qué versión de Aggrega se está ejecutando puede leer ambas ahí, sea cual sea la parte de la respuesta que le entregue la aplicación. Cuando ambas proceden de releases distintas, esa línea lo dice, nombrando las dos, y las indicaciones que el servidor entrega al asistente al conectarse comienzan con la misma frase. Nada se rechaza por una diferencia, y el servidor responde a cada solicitud como de costumbre; se informa de ello para que sepas qué ejecutable está ejecutando el paquete. Para igualarlos, instala el aggrega-<version>.mcpb de la release de la que procede tu ejecutable — aggrega version en un terminal imprime esa versión — o establece Path to the aggrega executable en la ruta completa de un aggrega de la release del paquete, y después reinicia la aplicación como en el paso 4.
Los registros propios de Claude Desktop muestran qué inició. En Windows pueden encontrarse en una carpeta de paquete dentro del directorio local de datos de aplicación en lugar de en %APPDATA%\Claude\logs, incluso cuando Claude Desktop se instaló desde su propia descarga: en %LOCALAPPDATA%\Packages\, en la carpeta cuyo nombre comienza por Claude_, en LocalCache\Local\Claude\logs. Los archivos que hay ahí incluyen mcp.log y mcp-server-Aggrega.log, y el segundo contiene lo que el servidor de Aggrega escribe en su salida de error estándar. Una línea que contiene Using MCP server command: nombra el comando que inició la aplicación, tomado del ajuste Path to the aggrega executable del paquete. Cuando el ajuste nombra una ruta en la que no hay nada, el registro contiene el mensaje del intérprete de comandos de Windows de que la ruta no se reconoce como un comando, y después informa de que el servidor no pudo iniciarse. Cuando la carpeta del workspace no existe — renombrada, movida o nunca creada —, el servidor se inicia de todos modos y responde a cada solicitud que el asistente hace en ese workspace con su rechazo, de modo que el asistente recibe el rechazo como respuesta a su solicitud en lugar de que la aplicación informe de un fallo de conexión. El rechazo nombra AGGREGA_WORKSPACE_ROOT como la variable que establece el ajuste Workspace folder del paquete, y cita la carpeta exactamente como la pasó la aplicación; mcp-server-Aggrega.log contiene el mismo rechazo. A un Workspace folder que se deja vacío se le responde del mismo modo, con el rechazo del paso 3 que nombra el ajuste vacío, y que el registro también contiene. Corrige el ajuste y reinicia la aplicación como en el paso 4.
La configuración de conectores de Claude Desktop es la otra vía, para un servidor al que se accede por HTTPS: consulta Un servidor al que se accede por HTTPS.
Cuando un cliente no acepta todo el conjunto de herramientas
Aggrega anuncia todo su conjunto de herramientas y deja que el cliente decida cuánto de él presenta al modelo. Algunos clientes limitan cuántas herramientas registran a la vez y descartan el resto. Cuando eso ocurre, mcp.announce_tools reduce lo que anuncia el servidor a las herramientas que nombres — consulta Restringir lo que anuncia el servidor.
Un servidor al que se accede por HTTPS
Cada entrada anterior inicia el servidor por sí misma. A un servidor que ejecuta otra persona — un único proceso de larga duración en un host, que sirve un workspace — se accede en cambio por la red, y su entrada nombra una dirección en lugar de un comando:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}La ruta es siempre /mcp; el host es el que el operador publicó para ese servidor. Pídeselo. Gemini CLI recibe la dirección en httpUrl en lugar de url: interpreta url como un servidor con el antiguo transporte de flujo de eventos y httpUrl como uno con el transporte HTTP transmisible, que es el que habla este servidor.
Es tu cliente quien obtiene el token, no tú. En la entrada no se configura nada sobre el inicio de sesión: el servidor responde a una solicitud no autenticada nombrando el documento que indica qué servidor de autorización emite sus tokens, y un cliente que habla el flujo de autorización del protocolo lee ese documento, te lleva a iniciar sesión y adjunta el token que recibe a cada solicitud posterior. Los nombres de los scopes que puede pedir se publican en ese mismo documento. Un cliente que no implementa el flujo no puede llegar a un servidor de este tipo, y nada que añadas a la entrada lo sustituye.
Una herramienta que los scopes de tu inicio de sesión no alcanzan sigue apareciendo en la lista de herramientas. Su llamada se rechaza, nombrando el scope que la permitiría, y un cliente que implementa el step-up del protocolo responde a ese rechazo pidiéndote que vuelvas a iniciar sesión para ese scope. A un cliente que no hace step-up se le pueden dar igualmente los scopes de escritura: quien gestiona el servidor de autorización los convierte en scopes predeterminados para ese cliente, de modo que su primer inicio de sesión ya los lleva — a costa de que cada inicio de sesión a través de ese cliente lleve entonces acceso de escritura. Qué puede alcanzar quien llama expone qué permite cada scope y cómo se comporta ese ajuste para un cliente que se registra de nuevo cada vez que se conecta.
Lo que requiere un servidor de este tipo, y lo que configura su operador, se describe en la página aggrega mcp de la referencia.
Verificar la conexión
Después de que el cliente se vuelva a conectar, confirma que la integración está activa: el cliente debería listar los prompts de redacción de Aggrega (uno para cada uno de los roles de desarrollo, arquitectura y operaciones, más una plantilla por entidad) y las herramientas de redacción — entre ellas scaffold, validate, describe y get-schema. Pide al asistente que genere el esqueleto de un componente, y debería devolver un esqueleto con los campos que exige un Component. Si no aparece nada, comprueba que aggrega version se ejecuta desde un terminal y que el command del cliente se resuelve en el binario — la nota sobre PATH de más arriba cubre la causa habitual.