Collegare il server MCP
Il server MCP di Aggrega è il comando aggrega mcp, e il binario aggrega è il suo unico prerequisito: Installare il binario lo installa con un solo comando. Il server viene eseguito come sottoprocesso del tuo client tramite stdio, legge i propri schemi dal binario e le pagine della documentazione da una copia che scarica una sola volta nella cache della tua macchina, e non richiede alcun servizio, porta o account separato. Se qualcun altro esegue già un server per te, non ti servono né il binario né nulla di tutto questo: vedi Un server raggiunto via HTTPS.
Client che lo aggiungono con un solo comando
Un assistente con il plugin di Aggrega installato è già collegato. L’installazione del plugin aggiunge la skill di Aggrega e il server in un solo passaggio — in Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro e OpenClaw, come descrive Installare il plugin — quindi per collegare quell’assistente non serve nient’altro di questa pagina. Il plugin avvia aggrega mcp usando l’aggrega presente nel PATH con cui è stato avviato l’assistente, quindi il binario deve essere installato lì. Alcuni assistenti avviano il server di un plugin nella cartella del plugin stesso anziché nel tuo progetto — Codex lo fa — e l’assistente indica allora la cartella del tuo progetto come workspace_root nelle chiamate che lo accettano; la skill gli dice di verificare in quale workspace risponde il server.
Senza il plugin, aggiungi il server con il comando del client stesso. In Claude Code:
claude mcp add --transport stdio aggrega -- aggrega mcpIn Codex:
codex mcp add aggrega -- aggrega mcpIn Gemini CLI:
gemini mcp add aggrega aggrega mcpOgni altro client
La maggior parte dei client compatibili con MCP avvia il server allo stesso modo — esegue il comando aggrega con un singolo argomento mcp e parla il protocollo sull’input e l’output standard del processo. Ciò che cambia tra loro è dove ciascuno conserva il proprio elenco di server e come chiama le voci al suo interno. La forma comune:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Una volta che il client si è riavviato e collegato, diventano disponibili i prompt, le risorse e gli strumenti di scrittura di Aggrega. Cosa può fare il tuo assistente con Aggrega li descrive, Scrivere file Aggrega mostra cosa farne, e il riferimento di aggrega mcp tratta il comando stesso.
Nulla nella voce seleziona una revisione del protocollo. Aggrega parla sia 2026-07-28 sia 2025-06-18, sull’input e l’output standard come tramite HTTPS, quindi un client dell’una o dell’altra si collega e raggiunge gli stessi prompt, risorse e strumenti. Quale richieda un client si decide sul canale anziché nella tua configurazione.
Un assistente in grado di eseguire comandi può fare tutto questo da solo — installare il binario, aggiungere la skill di Aggrega e collegarsi al server — a partire da un unico prompt che incolli al suo interno: vedi Configurare Aggrega con il tuo assistente AI.
Dove ogni client conserva il proprio elenco di server
| Client | Dove si trova l’elenco | Come si chiama la voce |
|---|---|---|
| Claude Code | claude mcp add, oppure un file .mcp.json nel progetto | mcpServers |
| Claude Desktop | le sue impostazioni delle estensioni per un server locale; le sue impostazioni dei connettori per uno raggiunto tramite HTTPS | vedi Claude Desktop |
| Cursor | .cursor/mcp.json per un workspace, oppure un mcp.json a livello utente per ogni workspace | mcpServers |
| Gemini CLI | gemini mcp add, oppure ~/.gemini/settings.json per ogni progetto e .gemini/settings.json per uno solo | mcpServers |
| Codex CLI | codex mcp add, oppure ~/.codex/config.toml per ogni progetto e .codex/config.toml per un singolo progetto attendibile | una tabella [mcp_servers.aggrega] — consulta Codex CLI |
| Zed | Settings → AI → MCP Servers, che scrive la voce nel file delle impostazioni di Zed | context_servers — consulta Zed |
| Visual Studio Code | mcp.json nel tuo profilo utente, oppure .vscode/mcp.json per un workspace | servers — vedi Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, oppure il file mcp-config.json che conserva nella tua directory home | mcpServers |
| Antigravity | il file mcp_config.json raggiungibile dalle sue impostazioni | mcpServers |
| Windsurf | il file mcp_config.json raggiungibile dalle sue impostazioni | mcpServers |
| Cline | le sue impostazioni MCP, basate su un file cline_mcp_settings.json | mcpServers |
Ogni client di quella tabella, tranne i quattro che hanno una sezione propria più sotto, accetta la voce esattamente come scritta sopra, nel percorso indicato nella sua riga. Un client non elencato si collega allo stesso modo se legge un elenco di server di una di queste forme.
Una nota sul PATH
I client avviati da un ambiente grafico non sempre ereditano lo stesso PATH del tuo terminale. Se un client segnala che non trova il comando aggrega, sostituisci "command": "aggrega" con il percorso assoluto del binario (ad esempio "command": "/home/you/.local/bin/aggrega", il percorso di installazione su Linux per un utente di nome you). Tutto il resto rimane uguale.
Visual Studio Code
Visual Studio Code conserva i propri server sotto servers anziché mcpServers, e ogni voce indica il trasporto che usa:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex mantiene i suoi server in TOML anziché in JSON — in ~/.codex/config.toml per ogni progetto, o in .codex/config.toml per un progetto che Codex considera attendibile — ciascuno come una tabella con il nome del server:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, il comando visto sopra, scrive la stessa tabella per te. L’estensione IDE di Codex e l’app desktop di ChatGPT leggono lo stesso file, quindi l’unica voce serve tutti e tre.
Zed
Zed mantiene i suoi server sotto context_servers nel suo file delle impostazioni. Aggiungi il server da Settings → AI → MCP Servers — Add Server, poi Add Local Server — che scrive la voce in quel file, oppure esegui zed: open settings file dalla palette dei comandi e aggiungi tu la voce:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed supporta gli strumenti e i prompt del protocollo, quindi il suo agente raggiunge gli strumenti e i prompt di authoring di Aggrega ma non le risorse che il server offre anch’esso.
Claude Desktop
Claude Desktop installa un server locale da un pacchetto di estensione — il server insieme a un manifest che lo descrive, raccolti in un unico file installabile e aggiunti dalle sue impostazioni delle estensioni — anziché da una voce in un file di configurazione. Ogni release di Aggrega include un pacchetto di questo tipo, aggrega-<version>.mcpb, accanto ai suoi binari precompilati.
Il pacchetto di Aggrega non contiene alcun programma proprio. Avvia un eseguibile aggrega già installato sulla tua macchina, con il singolo argomento mcp, e parla il protocollo sull’input e l’output standard di quel processo — lo stesso server che avvia ogni voce sopra. A meno che tu non scelga un altro eseguibile, consegna a Claude Desktop il nome di comando aggrega, come fa ogni voce sopra, così l’applicazione cerca aggrega nel PATH con cui è stata avviata; e consegna a quel server il workspace che scegli. Per aggiungerlo:
- Installa il binario
aggrega, come descritto in Installare il binario. Il comando di installazione e i passaggi manuali descritti lì lo collocano entrambi in una tua cartella — su Windows%LOCALAPPDATA%\Programs\aggregaanziché una cartella di sistema comeC:\Windows\System32— così da poterlo sostituire senza diritti di amministratore. - Installa
aggrega-<version>.mcpbdalle impostazioni delle estensioni di Claude Desktop. - Configura le impostazioni del pacchetto; nessuna delle due è obbligatoria. Path to the aggrega executable è il programma che il pacchetto avvia, e il suo valore predefinito è il nome di comando
aggrega, che l’applicazione cerca nelPATHcon cui è stata avviata. Una cartella aggiunta al tuoPATHmentre l’applicazione è in esecuzione — come fanno con la propria il programma di installazione per Windows e il comando di installazione su Windows — raggiunge l’applicazione solo dopo che questa è stata chiusa e riavviata, come al passaggio 4, e un’applicazione avviata da un ambiente grafico potrebbe non vedere lo stessoPATHdel tuo terminale (vedi Una nota suPATH). Lascia il valore predefinito quando l’aggregain quelPATHè l’eseguibile che vuoi. Imposta invece il campo sul percorso completo di un eseguibile quando quello che vuoi non è in quelPATH, o è unaggregadiverso dal primo trovato lì — su macOS e Linux, per la posizione di installazione, l’aggregain.local/binnella tua cartella home, come/Users/you/.local/bin/aggrega; su Windows il percorso completo che termina inaggrega.exe, comeC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Per tornare al valore predefinito, imposta il campo suaggregaanziché svuotarlo. Dove non è installato alcunaggrega, installalo come descrive il passaggio 1. Workspace folder è la cartella del workspace Aggrega in cui lavora l’assistente: la cartella che contiene il.aggrega-config.yamldel tuo progetto. Imposta questa: è vuota finché non scegli una cartella, e finché è vuota il pacchetto consegna al server unAGGREGA_WORKSPACE_ROOTvuoto, così il server risponde a ogni richiesta che l’assistente fa nel workspace con un rifiuto che dice che l’impostazione Workspace folder è vuota e ti chiede di impostarla sulla cartella che contiene il.aggrega-config.yamldel tuo workspace, anziché lavorare nella cartella in cui Claude Desktop lo ha avviato. Il pacchetto consegna la cartella al server solo quando l’applicazione lo avvia, quindi una cartella impostata mentre il server è in esecuzione ha effetto dopo che disattivi e riattivi l’estensione nelle impostazioni delle estensioni, o riavvii l’applicazione come al passaggio 4. - Chiudi completamente Claude Desktop, poi avvialo di nuovo. Un server già avviato dall’applicazione continua a funzionare, e rinominare l’eseguibile non lo ferma, quindi un’impostazione modificata ha effetto solo quando l’applicazione avvia di nuovo il server: dopo che è stata chiusa e riavviata o, per Workspace folder, dopo che l’estensione è stata disattivata e riattivata. Su Windows, Gestione attività mostra se un processo
aggregaè ancora in esecuzione.
La cartella del workspace è il luogo in cui si risponde a ogni richiesta che non indica un workspace proprio. Claude Desktop avvia il server in una cartella scelta da sé anziché nel tuo progetto, quindi il pacchetto passa al server la cartella che hai scelto come variabile AGGREGA_WORKSPACE_ROOT nel suo ambiente, anziché come argomento sulla riga di comando composta dall’applicazione. Il server prende quella cartella come radice del workspace stessa, come viene preso --workspace-root su ogni comando: non cerca sopra di essa un workspace che la contenga, quindi scegli la cartella che contiene .aggrega-config.yaml anziché una al suo interno. Per lavorare in un altro workspace, modifica l’impostazione e riavvia l’applicazione come al passaggio 4. In una richiesta che indica un workspace proprio con un workspace_root relativo, anche questo viene letto a partire dalla cartella del workspace, quindi un prompt indica una cartella al suo interno — come quickstart-ai/1 — senza sapere dove si trova la cartella sulla tua macchina; un workspace_root assoluto viene usato così com’è. Finché l’impostazione è vuota, a uno relativo si risponde con lo stesso rifiuto di una richiesta che non ne indica nessuno.
Poiché il pacchetto non indica alcun eseguibile di alcuna piattaforma, lo stesso file vale per ogni piattaforma che dichiara: macOS, Windows e Linux.
Il server riporta quale aggrega ha avviato il pacchetto. Le impostazioni delle estensioni di Claude Desktop elencano la versione del pacchetto stesso — la versione della release da cui proviene — e non la versione dell’eseguibile che il pacchetto avvia. I due si installano separatamente, quindi possono provenire da release diverse. Il pacchetto passa al server la propria versione come variabile AGGREGA_BUNDLE_VERSION nel suo ambiente, e il server le riporta entrambe: la risposta di describe-capabilities chiamato senza argomenti — lo strumento che un assistente chiama per sapere che cosa offre il server — si apre con una riga che indica la versione dell’eseguibile e quella del pacchetto, e porta la stessa riga come version_summary nella sua parte strutturata, così un assistente a cui si chiede quale versione di Aggrega è in esecuzione può leggerle entrambe lì, qualunque parte della risposta gli consegni l’applicazione. Dove le due provengono da release diverse, quella riga lo dice, indicandole entrambe, e le indicazioni che il server consegna all’assistente quando si collega si aprono con la stessa frase. Nulla viene rifiutato per una differenza, e il server risponde a ogni richiesta come di consueto; viene riportata perché tu sappia quale eseguibile sta eseguendo il pacchetto. Per allinearli, installa l’aggrega-<version>.mcpb della release da cui proviene il tuo eseguibile — aggrega version in un terminale stampa quella versione — oppure imposta Path to the aggrega executable sul percorso completo di un aggrega della release del pacchetto, quindi riavvia l’applicazione come al passaggio 4.
I log di Claude Desktop mostrano che cosa ha avviato. Su Windows possono trovarsi sotto una cartella di pacchetto nella directory dei dati applicativi locali anziché sotto %APPDATA%\Claude\logs, anche dove Claude Desktop è stato installato dal suo download: sotto %LOCALAPPDATA%\Packages\, nella cartella il cui nome inizia con Claude_, in LocalCache\Local\Claude\logs. I file lì includono mcp.log e mcp-server-Aggrega.log, il secondo con ciò che il server Aggrega scrive sul proprio standard error. Una riga che contiene Using MCP server command: indica il comando avviato dall’applicazione, ricavato dall’impostazione Path to the aggrega executable del pacchetto. Quando l’impostazione indica un percorso in cui non c’è nulla, il log riporta il messaggio dell’interprete dei comandi di Windows secondo cui il percorso non è riconosciuto come comando, poi segnala che il server non ha potuto avviarsi. Quando la cartella del workspace non c’è — rinominata, spostata o mai creata — il server si avvia comunque e risponde a ogni richiesta che l’assistente fa in quel workspace con il proprio rifiuto, così l’assistente riceve il rifiuto come risposta alla sua richiesta anziché l’applicazione segnalare un errore di connessione. Il rifiuto indica AGGREGA_WORKSPACE_ROOT come la variabile impostata dall’impostazione Workspace folder del pacchetto, e cita la cartella esattamente come l’applicazione l’ha passata; mcp-server-Aggrega.log riporta lo stesso rifiuto. A una Workspace folder lasciata vuota si risponde allo stesso modo, con il rifiuto del passaggio 3 che indica l’impostazione vuota, riportato anch’esso nel log. Correggi l’impostazione e riavvia l’applicazione come al passaggio 4.
Le impostazioni dei connettori di Claude Desktop sono l’altra strada, per un server raggiunto tramite HTTPS: consulta Un server raggiunto tramite HTTPS.
Quando un client non accetta l’intera superficie degli strumenti
Aggrega annuncia l’intera superficie dei propri strumenti e lascia al client la decisione su quanta di essa presentare al modello. Alcuni client limitano il numero di strumenti che registrano in una volta e scartano il resto. In quel caso, mcp.announce_tools riduce ciò che il server annuncia agli strumenti che indichi — consulta Restringere ciò che il server annuncia.
Un server raggiunto tramite HTTPS
Ogni voce sopra avvia il server da sé. Un server eseguito da qualcun altro — un unico processo di lunga durata su un host, che serve un workspace — si raggiunge invece attraverso la rete, e la sua voce indica un indirizzo anziché un comando:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}Il percorso è sempre /mcp; l’host è quello che l’operatore ha pubblicato per quel server. Chiedilo a lui. Gemini CLI accetta l’indirizzo sotto httpUrl anziché url: interpreta url come un server sul vecchio trasporto a flusso di eventi e httpUrl come un server sul trasporto HTTP streamable, che è quello parlato da questo server.
È il tuo client a ottenere il token, non tu. Nella voce non si configura nulla riguardo all’accesso: il server risponde a una richiesta non autenticata indicando il documento che dice quale server di autorizzazione emette i suoi token, e un client che parla il flusso di autorizzazione del protocollo legge quel documento, ti fa accedere e allega il token che riceve a ogni richiesta successiva. I nomi degli scope che può richiedere sono pubblicati nello stesso documento. Un client che non implementa il flusso non può raggiungere un server di questo tipo, e nulla che tu aggiunga alla voce può sostituirlo.
Uno strumento che gli scope del tuo accesso non raggiungono è comunque nell’elenco degli strumenti. La sua chiamata viene rifiutata, indicando lo scope che la consentirebbe, e un client che implementa lo step-up del protocollo risponde a quel rifiuto chiedendoti di accedere di nuovo per quello scope. A un client che non fa step-up si possono comunque dare gli scope di scrittura: chi gestisce il server di autorizzazione li rende scope predefiniti per quel client, così il suo primo accesso li porta già — con il costo che ogni accesso tramite quel client porta poi la portata in scrittura. Che cosa può raggiungere un chiamante espone che cosa consente ciascuno scope e come si comporta quell’impostazione per un client che si registra di nuovo a ogni connessione.
Ciò che un server di questo tipo richiede, e ciò che il suo operatore configura, è descritto nella pagina aggrega mcp del riferimento.
Verificare la connessione
Dopo che il client si è ricollegato, verifica che l’integrazione sia attiva: il client dovrebbe elencare i prompt di scrittura di Aggrega (uno ciascuno per i ruoli di sviluppatore, architetto e operations, più un modello per singola entità) e gli strumenti di scrittura — tra cui scaffold, validate, describe e get-schema. Chiedi all’assistente di creare lo scheletro di un componente, e dovrebbe restituire uno scheletro che contiene i campi richiesti da un Component. Se non compare nulla, verifica che aggrega version funzioni da un terminale e che il command del client si risolva nel binario — la nota sul PATH più sopra copre la causa comune.