Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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:

Terminal window
claude mcp add --transport stdio aggrega -- aggrega mcp

In Codex:

Terminal window
codex mcp add aggrega -- aggrega mcp

In Gemini CLI:

Terminal window
gemini mcp add aggrega aggrega mcp

Ogni 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

ClientDove si trova l’elencoCome si chiama la voce
Claude Codeclaude mcp add, oppure un file .mcp.json nel progettomcpServers
Claude Desktople sue impostazioni delle estensioni per un server locale; le sue impostazioni dei connettori per uno raggiunto tramite HTTPSvedi Claude Desktop
Cursor.cursor/mcp.json per un workspace, oppure un mcp.json a livello utente per ogni workspacemcpServers
Gemini CLIgemini mcp add, oppure ~/.gemini/settings.json per ogni progetto e .gemini/settings.json per uno solomcpServers
Codex CLIcodex mcp add, oppure ~/.codex/config.toml per ogni progetto e .codex/config.toml per un singolo progetto attendibileuna tabella [mcp_servers.aggrega] — consulta Codex CLI
ZedSettings → AI → MCP Servers, che scrive la voce nel file delle impostazioni di Zedcontext_servers — consulta Zed
Visual Studio Codemcp.json nel tuo profilo utente, oppure .vscode/mcp.json per un workspaceservers — vedi Visual Studio Code
GitHub Copilot CLIcopilot mcp add, oppure il file mcp-config.json che conserva nella tua directory homemcpServers
Antigravityil file mcp_config.json raggiungibile dalle sue impostazionimcpServers
Windsurfil file mcp_config.json raggiungibile dalle sue impostazionimcpServers
Clinele sue impostazioni MCP, basate su un file cline_mcp_settings.jsonmcpServers

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:

  1. 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\aggrega anziché una cartella di sistema come C:\Windows\System32 — così da poterlo sostituire senza diritti di amministratore.
  2. Installa aggrega-<version>.mcpb dalle impostazioni delle estensioni di Claude Desktop.
  3. 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 nel PATH con cui è stata avviata. Una cartella aggiunta al tuo PATH mentre 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 stesso PATH del tuo terminale (vedi Una nota su PATH). Lascia il valore predefinito quando l’aggrega in quel PATH è l’eseguibile che vuoi. Imposta invece il campo sul percorso completo di un eseguibile quando quello che vuoi non è in quel PATH, o è un aggrega diverso dal primo trovato lì — su macOS e Linux, per la posizione di installazione, l’aggrega in .local/bin nella tua cartella home, come /Users/you/.local/bin/aggrega; su Windows il percorso completo che termina in aggrega.exe, come C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Per tornare al valore predefinito, imposta il campo su aggrega anziché svuotarlo. Dove non è installato alcun aggrega, 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.yaml del tuo progetto. Imposta questa: è vuota finché non scegli una cartella, e finché è vuota il pacchetto consegna al server un AGGREGA_WORKSPACE_ROOT vuoto, 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.yaml del 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.
  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.