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

Importare la configurazione di un client MCP

Questa procedura guidata importa i server Model Context Protocol con cui è configurato un assistente di programmazione — due che avvia da una riga di comando e uno gestito da qualcun altro — e compila i server per Kubernetes, così che un agente in esecuzione in un cluster possa raggiungere gli stessi strumenti. L’importazione produce in bozza ogni file che la build legge: la riga di comando o l’indirizzo di ogni server, la realizzazione che lo esegue e la provenienza del token del server GitHub. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; la configurazione e ogni fase della procedura si trovano nell’esempio import-mcp, dove uno script di verifica esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file lì conservati, e convalida e compila ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-mcp

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-mcp

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra la sua configurazione MCP con tre server: github, fetch e docs-search.

La configurazione

Il .mcp.json di Claude Code, nella radice di un progetto:

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"docs-search": {
"type": "http",
"url": "https://mcp.example.com/docs/mcp",
"headers": {
"Authorization": "Bearer ${DOCS_API_KEY}"
}
}
}
}

L’importazione legge allo stesso modo il claude_desktop_config.json di Claude Desktop, il .cursor/mcp.json di Cursor, il .vscode/mcp.json di Visual Studio Code e un server.json di un registry MCP. Accanto alla configurazione, un .aggrega-config.yaml rende la cartella un workspace:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside .mcp.json.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

--target abbozza un Manifest a partire dalle Recipes del catalogo. Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui recupera il proprio importer: uno snapshot firmato del catalogo pubblicato, che la prima importazione recupera, verifica e conserva nella cache dei contenuti dello spazio di lavoro, e che il record scritto dall’importazione accanto alle sue bozze indica tramite il suo digest. Uno spazio di lavoro che indica le proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, oppure sotto workspace.catalog_dirs — importa invece rispetto a quelle.

Il file delle risposte

Su Kubernetes, il server GitHub legge il proprio token da un Secret custodito dal cluster, e nessuna configurazione MCP nomina quel Secret: la configurazione legge il token dalla variabile GITHUB_TOKEN della tua shell. Per questo l’importazione chiede il nome del Secret. L’esempio conserva la risposta in import-answers.yaml, accanto a .mcp.json, dove l’importazione la cerca:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.github.features.server_env.infra.origin: "github-mcp-token"

L’importazione ha scritto il file da sé, la prima volta che è stata eseguita senza risposta: non avendo un terminale a cui porre la domanda, ha abbozzato tutto il resto, ha lasciato vuoto il nome del Secret, ha elencato la chiave nel file e si è fermata con

1 value the drafts leave empty is still owed, listed in the answers file <workspace>/import-answers.yaml: write it beside its key there, then run the import again

Da un terminale pone invece la domanda e scrive la risposta nel file per l’importazione successiva. La risposta è il nome del Secret, github-mcp-token, mai il token. Il file delle risposte dell’importazione descrive per intero il file e le domande.

aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.

Entra in source:

Terminal window
cd source

Eseguire l’importazione

Terminal window
aggrega import .mcp.json --target helm

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the mcp format, with drafted paths relative to <workspace>
warn: the value of infra.stdio_command.0 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.2 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.0 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of headers.Authorization of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.endpoint of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
Pull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest abbozzati compaiono accanto alla configurazione MCP, l’output di Aggrega elenca i valori riportati così come sono scritti e i file scritti, e una notifica indica che l’importazione ha abbozzato 3 file, riconosciuti come mcp.

Ogni server è un’istanza dello strumento MCP della libreria standard, core/ai-tool/mcp, quindi l’importazione non valuta alcun candidato e non stampa alcuna riga mapped.

  • Le righe warn nominano i valori contenuti nella configurazione di un server. Nessun client MCP ne contrassegna alcuno come credenziale, e ognuno di essi può contenerne una — una chiave in un argomento della riga di comando, un token in un indirizzo —, quindi l’importazione nomina ogni elemento di una riga di comando, ogni header e ogni indirizzo che ha riportato, tramite il suo server e la sua posizione, mai tramite il suo valore. Leggili prima di condividere la bozza. Il valore ${GITHUB_TOKEN} di env è un riferimento a una variabile e nient’altro, quindi non contiene alcun valore proprio e nessun avviso lo nomina.
  • La riga Pull complete è l’import che recupera ciò da cui dipende la Release generata in bozza, come fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da eseguire.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/mcp, dal file, .mcp.json, poiché la configurazione di un client non porta un nome proprio — il server.json di un registro prende il nome dal suo name — nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — un’istanza per server, e ancora nulla che le usi:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
github:
type: core/ai-tool/mcp
fetch:
type: core/ai-tool/mcp
docs-search:
type: core/ai-tool/mcp

release.yaml — come ciascun server viene eseguito o raggiunto, così come lo indica la configurazione, e il Secret da cui viene letto il token del server GitHub:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
manifest: imported/mcp
components:
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: "github-mcp-token"
fetch:
infra:
stdio_command:
- "uvx"
- "mcp-server-fetch"
stdio_runtime: pypi
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${DOCS_API_KEY}"
docs-search:
infra:
endpoint: "https://mcp.example.com/docs/mcp"
  • L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessuna configurazione ne indica uno; cambialo se la Release viene distribuita altrove.
  • stdio_runtime si ricava da ciascun comando: npx esegue un pacchetto npm, uvx uno PyPI.
  • Il token GitHub. L’ambiente del server diventa il suo slot server_env. Su Kubernetes, la realizzazione di core/referenced-secret-set, helm/k8s-secret-set, scrive i valori che riceve in un Secret che la build renderizza, il che metterebbe il token in un file. Per questo, con --target helm l’importazione associa invece core/referenced-secret, che nomina un Secret che il cluster contiene già — la risposta, github-mcp-token — con una chiave dati per variabile, GITHUB_PERSONAL_ACCESS_TOKEN. Il bridge importa ogni chiave dati di quel Secret come variabile con lo stesso nome, così il server legge il proprio token come faceva sulla tua macchina, e nessun file renderizzato lo contiene.
  • L’header Authorization resta un commento. La credenziale di un server remoto è detenuta da chi lo chiama, sulla connessione di quel chiamante allo strumento, e questo workspace non ha ancora alcun chiamante. Quando colleghi un agente a docs-search, l’header va su quella connessione.

manifest.yaml — una realizzazione per server, in base al nome, e la realizzazione del Secret:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
github: helm/mcp-stdio-bridge
fetch: helm/mcp-stdio-bridge
docs-search: helm/mcp-remote
features:
type:
core/referenced-secret: helm/k8s-existing-secret

Tre Recipes Kubernetes realizzano core/ai-tool/mcp — una per un server pubblicato come immagine, una per un pacchetto eseguito dietro un bridge, una per un server gestito da qualcun altro — e quale sia adatta è una proprietà di ciascun server, indicata dalla configurazione. Per questo l’importazione mappa ciascuna istanza per nome: github e fetch, avviati da una riga di comando, vengono eseguiti dietro il bridge stdio, helm/mcp-stdio-bridge; docs-search, gestito da qualcun altro, è mappato su helm/mcp-remote, che non esegue nulla e pubblica l’indirizzo. Il Secret del token è mappato su helm/k8s-existing-secret, che fa riferimento a un Secret anziché scriverne uno.

release.lock registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.

Su Docker Compose

I server si eseguono anche su Docker Compose. aggrega import .mcp.json --target compose mappa github e fetch su compose/mcp-stdio-bridge e docs-search su compose/mcp-remote, e mantiene l’ambiente del server GitHub così come lo scrive la configurazione: una voce di core/referenced-secret-set il cui valore è il riferimento alla variabile ${GITHUB_TOKEN}, realizzata da compose/dotenv-secret-set, che lo scrive così com’è nell’ambiente del servizio, in modo che Docker Compose lo valorizzi dalla tua shell all’avvio dello stack. Quell’importazione non chiede nulla e mantiene il nome del Secret nel file delle risposte senza usarlo.

Convalidare e compilare

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release abbozzata aperta nell’editor dopo la validazione, con l’output di Aggrega e una notifica che non segnalano alcun problema.

La build della Release abbozzata: nell’Explorer compare una cartella dist, l’output di Aggrega elenca un Deployment e un Service per ogni server, e una notifica indica che sono stati scritti 5 file.

La convalida stampa:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

e la build, dove <workspace> indica la cartella in cui l’hai eseguita:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 5 files written to <workspace>/dist

La riga notice è informativa: la Feature accetta il proprio origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

La build scrive, sotto dist/helm/, un Deployment e un Service per ciascuno dei due server dietro il bridge, e un Service per docs-search. Il container del server GitHub, in dist/helm/github-deployment.yaml, esegue il bridge con la riga di comando del server e prende il proprio ambiente dal Secret:

containers:
- name: main
image: ghcr.io/supercorp-ai/supergateway:4.1.0@sha256:1938c43538a5308bce07d58028e9de00b7acfecb40b39b059b2f3931800ad910
args:
- --stdio
- '''npx'' ''-y'' ''@modelcontextprotocol/server-github'''
- --outputTransport
- streamableHttp
- --stateful
- --port
- "8080"
- --streamableHttpPath
- /mcp
- --healthEndpoint
- /healthz
ports:
- name: http
containerPort: 8080
env:
- name: MCP_TOOL_SIDE_EFFECTS
value: mutating
- name: MCP_TOOL_TIMEOUT_SECONDS
value: "30"
- name: MCP_TOOL_PORT
value: "8080"
envFrom:
- secretRef:
name: github-mcp-token
[… omitted: the container's resources and its readiness probe]

dist/helm/docs-search-service.yaml non esegue nulla: dà al server gestito da qualcun altro un nome all’interno del cluster.

apiVersion: v1
kind: Service
metadata:
name: docs-search
[… omitted: the labels and annotations the build writes on every resource]
spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `import-mcp`, chiama una volta lo strumento `scaffold` con `example` impostato su `import-mcp` e senza `dir`: scrive l’esempio in una nuova cartella `import-mcp`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato su `import-mcp/source`, `source` impostato su `.mcp.json` e `target` impostato su `helm`: legge le risposte di cui ha bisogno da `import-answers.yaml` accanto a `.mcp.json`, scrive le bozze in `import-mcp/source` ed esegue il pull di ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato su `import-mcp/source` e `release` impostato su `release.yaml`, e lo strumento `build` con `workspace_root` impostato su `import-mcp/source`, `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano sotto `import-mcp/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-mcp/source, in cui l’importazione ha scritto le bozze. La cartella contiene una sola Release, il release.yaml abbozzato, quindi l’editor la seleziona per te e, mentre modifichi le bozze, le verifica rispetto a quella Release, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file in dist/ all’interno della cartella. Usare Aggrega in Visual Studio Code descrive il resto.

Esecuzione

Nulla nella build scrive il Secret github-mcp-token, quindi crealo prima di applicare i file. Scrivi il tuo token in github-token.env, come l’unica riga GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, e crea il Secret a partire da esso. A quel punto il cluster conserva il token, quindi elimina il file:

Terminal window
kubectl create secret generic github-mcp-token --from-env-file=github-token.env
rm github-token.env
secret/github-mcp-token created

Applica la build, come spiega il passo di esecuzione di Come si svolge un’importazione, e attendi i due server:

Terminal window
kubectl apply -R -f dist/helm/
kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5m
service/docs-search created
service/fetch-default created
deployment.apps/fetch created
service/github-default created
deployment.apps/github created
deployment.apps/fetch condition met
deployment.apps/github condition met

Su Docker Compose, in un workspace importato con --target compose e compilato, avvia lo stack con il tuo token in GITHUB_TOKEN della tua shell, che Docker Compose legge all’avvio dello stack:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --wait

Eseguire il test

Il bridge serve ogni server tramite il trasporto Streamable HTTP di MCP, su /mcp alla porta 8080. Chiedi al server fetch di aprire una sessione con la richiesta initialize di MCP, che non legge alcun token.

Su Docker Compose, inviala da un container usa e getta sulla rete dello stack, mcp_compose, dove il nome del server è fetch:

Terminal window
docker run --rm --network mcp_compose curlimages/curl:8.11.1 -sS http://fetch:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
[… omitted: the same comment, repeated while the server starts]
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

Su Kubernetes, inoltra una porta locale verso il Service del server, fetch-default, e lascia il comando in esecuzione:

Terminal window
kubectl port-forward svc/fetch-default 8080:8080

Da un altro terminale, invia la stessa richiesta alla porta inoltrata:

Terminal window
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
: keepalive
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

La risposta nomina il server, mcp-fetch. Richiede un po’ di tempo: il bridge avvia la riga di comando del server, uvx mcp-server-fetch, per ogni sessione, e uvx prima scarica e installa i pacchetti del server — nell’esecuzione, circa mezzo minuto su Kubernetes e circa un minuto su Docker Compose. Le righe : keepalive sono commenti che lo stream invia nel frattempo.

Il server GitHub risponde alla stessa richiesta su http://github:8080/mcp in Docker Compose, e tramite kubectl port-forward svc/github-default 8080:8080 su Kubernetes. initialize non legge alcun token, quindi risponde qualunque cosa contenga il token; l’esecuzione ha usato un token segnaposto:

[… omitted: the keepalive comments, sent while npx installs the server]
event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-mcp-server","version":"0.6.2"}},"jsonrpc":"2.0","id":1}

Interrompi l’inoltro della porta, poi rimuovi ciò che hai applicato e il Secret:

Terminal window
kubectl delete -R -f dist/helm/
kubectl delete secret github-mcp-token

Su Docker Compose, arresta e rimuovi lo stack:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml down