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

L’indirizzo di uno strumento da un Secret — un server Model Context Protocol che legge la propria chiave dal proprio indirizzo

Alcuni server Model Context Protocol gestiti da altri leggono la propria chiave dal proprio indirizzo — https://mcp.example.com/mcp?api_key=<key> — anziché da un header della richiesta. Un indirizzo del genere non può essere scritto nello strumento come uno ordinario: lo strumento pubblica il proprio indirizzo così come è scritto, quindi la chiave raggiungerebbe ogni file che l’indirizzo raggiunge.

Questo workspace conserva l’indirizzo in due parti. Lo strumento, core/ai-tool/mcp, contiene l’indirizzo senza la parte che porta la chiave. La connessione dell’agente allo strumento contiene l’intero indirizzo come segreto, e la Release indica dove si trova. Si compila per Kubernetes e per Docker Compose, e su entrambi nessun file renderizzato porta la chiave.

L’agente è dichiarato nel catalogo proprio di questo workspace, quindi il socket che contiene l’indirizzo è scritto qui per intero. I runtime per agenti della libreria standard core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk e mastra, e le piattaforme core/ai-agent/flowise e n8n, dichiarano un socket tools con gli stessi due slot. Lo strumento, le due Features di credenziali e le loro realizzazioni sono forniti nel catalogo della libreria standard.

Che cosa costruisce

istanzaComponent del catalogoche cosa è qui
searchcore/ai-tool/mcpun server Model Context Protocol gestito da altri, mappato su mcp-remote, che non esegue nulla
agentlocal/ai-agent/mcp-clientl’agente, cablato a search tramite il suo socket tools

Due Releases condividono l’unico Aggregate, ciascuna con un proprio Manifest:

ReleaseManifestdestinazioneda dove proviene l’intero indirizzo
release-helm.yamlmanifest-helm.yamlKubernetesun Secret che il namespace contiene già: core/referenced-secret legato a helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeun riferimento a una variabile Compose: core/secret-value legato a compose/dotenv-secret

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

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

Terminal window
aggrega scaffold --example mcp-address-from-secret

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd mcp-address-from-secret

Build

Terminal window
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/
aggrega build --release release-compose.yaml --auto-pull # → dist/local/

Ogni Release scrive nella propria directory, così i due alberi renderizzati coesistono e possono essere confrontati fianco a fianco.

.aggrega-config.yaml elenca il catalog/ proprio di questo workspace, che contiene l’agente e le sue due Recipes; tutto il resto si risolve da hub.aggrega.ai, il registry predefinito che indica. Con un checkout del catalogo della libreria standard (dove procurarselo) indicato con --catalog, ogni entità si risolve da quelle due directory, quindi il build si completa anche con --offline, che rifiuta ogni accesso alla rete. --auto-pull scrive il lockfile di ciascuna Release durante il build; i lockfile e l’output renderizzato sono generati, non forniti.

Il build per Kubernetes stampa, con <workspace> al posto della cartella di questo esempio:

Pull complete: release-helm.lock (entities=11, source_artifacts=0, external_inputs=0)
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: 2 files written to <workspace>/dist

Il build per compose stampa le stesse righe per release-compose.yaml, con il suo avviso che nomina core/secret-value, e scrive un file. La riga notice: riguarda la Feature di credenziale che la Release associa: accetta il localizzatore del segreto, origin, dai values dello sviluppatore o dall’infra dell’operatore, e l’avviso segnala che una foglia è dichiarata in entrambi i pilastri. Non cambia alcun verdetto né alcun byte renderizzato.

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `mcp-address-from-secret`, chiama una volta lo strumento `scaffold` con `example` impostato su `mcp-address-from-secret` e senza `dir`: scrive l’esempio in una nuova cartella `mcp-address-from-secret`. Poi chiama lo strumento `build` una volta per ogni Release, in questo ordine — `release-helm.yaml` e `release-compose.yaml` — ogni volta con `workspace_root` impostato su `mcp-address-from-secret`, `release` impostato su quel file, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto ciascuna build; si trovano in `mcp-address-from-secret/dist/`.

Lo strumento contiene l’indirizzo senza la sua chiave

Da release-helm.yaml:

search:
infra:
endpoint: https://mcp.example.com/mcp

helm/mcp-remote legge da quell’indirizzo l’host, la porta e lo schema che pubblica, ed emette un file per lo strumento: un Service ExternalName che mappa un nome interno al cluster sull’host. L’intero spec di dist/kubernetes/helm/search-service.yaml:

spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

Quindi l’indirizzo che lo strumento contiene richiede almeno uno schema e un host, e non contiene nulla della parte che porta la chiave. compose/mcp-remote non definisce alcun servizio per lo strumento.

La connessione dell’agente contiene l’intero indirizzo

Il Component dell’agente dichiara due slot di segreto sul suo socket tools. Da catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, senza le descrizioni:

tools:
selector: "component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http"
valueSchema:
unauthenticated:
type: boolean
default: false
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
endpoint:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

credential contiene una chiave che l’agente presenta in un header della richiesta; endpoint contiene l’intero indirizzo, per un server che legge la propria chiave dall’indirizzo stesso. unauthenticated è la dichiarazione della connessione stessa che il suo strumento non richiede alcuna credenziale, e non cambia nulla di ciò che l’agente renderizza. Tutti e tre stanno sulla connessione, quindi un agente che raggiunge diversi server conserva il segreto di ciascun server sulla connessione di quel server.

La Release valorizza endpoint sulla connessione che l’Aggregate ha cablato. Da release-helm.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/referenced-secret
infra:
origin: search-mcp-address

Una Release non scrive values, quindi origin si trova in infra, e la chiave dei dati letta dal Secret è quella predefinita della Feature, value. Il Manifest lega core/referenced-secret a helm/k8s-existing-secret, che legge origin come il nome di un Secret che il namespace contiene già e non renderizza nulla. Il Secret viene creato al di fuori della Release, da chi la distribuisce:

Terminal window
kubectl -n agents create secret generic search-mcp-address \
--from-literal=value='https://mcp.example.com/mcp?api_key=<key>'

Il container dell’agente legge l’indirizzo da esso. L’env di dist/kubernetes/helm/agent-deployment.yaml:

env:
- name: MCP_URL_SEARCH
valueFrom:
secretKeyRef:
name: search-mcp-address
key: value
- name: MCP_HOST_SEARCH
value: mcp.example.com

MCP_URL_SEARCH è l’intero indirizzo, letto dal Secret per nome e chiave dei dati; MCP_HOST_SEARCH è l’host che lo strumento pubblica. dist/kubernetes/helm/ contiene il Deployment dell’agente e il Service dello strumento e nient’altro: non viene renderizzato alcun Secret, e nessun file porta la chiave.

Su Docker Compose

Compose non ha alcun riferimento a segreti, quindi la Release per compose valorizza lo stesso slot con core/secret-value, con un riferimento a una variabile Compose come origine. Da release-compose.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/secret-value
infra:
origin: "${SEARCH_MCP_URL}"

compose/dotenv-secret consegna il riferimento così come è scritto, e il servizio dell’agente lo porta. L’environment del servizio agent in dist/local/compose/docker-compose.yaml, che definisce quel servizio e nessun altro:

environment:
MCP_HOST_SEARCH: mcp.example.com
MCP_URL_SEARCH: ${SEARCH_MCP_URL}

Docker Compose sostituisce SEARCH_MCP_URL all’avvio dello stack — dall’ambiente della shell, da un file indicato con --env-file o dal file .env nella directory del progetto — quindi il file porta soltanto il riferimento.

Come le Recipes dell’agente leggono lo slot

Ogni connessione sul socket tools diventa variabili d’ambiente chiamate con l’alias della connessione in maiuscolo: MCP_HOST_<ALIAS> dall’host che lo strumento pubblica, e MCP_URL_<ALIAS> dall’indirizzo che lo strumento pubblica — a meno che la connessione non porti un segreto endpoint, nel qual caso MCP_URL_<ALIAS> è quel segreto e l’indirizzo pubblicato non viene consegnato affatto. Una connessione che porta una credential aggiunge MCP_CREDENTIAL_<ALIAS> e MCP_CREDENTIAL_HEADER_<ALIAS>, l’header della richiesta, pubblicato dallo strumento, con cui presentarla.

  • Su Kubernetes il segreto è una voce di associazione che nomina la connessione e lo slot — connection: search, from: endpoint, as: env — che il provider trasforma nel secretKeyRef mostrato sopra, leggendo il nome e la chiave dei dati del Secret da ciò che helm/k8s-existing-secret pubblica.
  • Su Docker Compose il segreto arriva sul canale di iniezione dell’agente sotto la chiave con cui la sua associazione lo ha consegnato, values.key, e la Recipe scrive quel valore nell’ambiente del servizio.

Se invece è scritta nell’infra.endpoint dello strumento, la chiave va ovunque vada l’indirizzo pubblicato: la MCP_URL_SEARCH dell’agente la porta come valore letterale, nel Deployment su Kubernetes e nell’ambiente del servizio nel file Compose, perché la realizzazione di riferimento pubblica l’indirizzo così come è scritto.

Limiti

  • Su Docker Compose, due segreti che solo la Release associa a un agente entrano in collisione. Ogni associazione core/secret-value fatta da una Release consegna sotto la chiave predefinita della Feature, value, quindi una seconda sullo stesso agente — l’indirizzo di un altro server, o una credenziale accanto a questa — arresta il build. Una Release che associa sia un endpoint sia una credential a search stampa:

    [… omitted: what resolving the lockfile prints, the same halt among it, and the notice about core/secret-value]
    [OPS_ERROR E0318] release-compose.yaml at .spec.boundaries.main.components.agent.uses.tools.search.features.credential
    duplicate delivery key across two attachments: an attachment's FeatureRecipe writes a delivery key another attachment already delivered ("value", mechanism "env", attachment "search.credential", delivered first by attachment "search.endpoint"). Give one of the two attachments a key of its own, or attach one fewer: the key this attachment delivers under is chosen by its FeatureRecipe, which can read the attachment's own values and infra, and the other's is chosen the same way or by its own inject block where it delivered through one. A Release sets an attachment's infra and never its values, so where a key is chosen by a value, attach that attachment in the Aggregate with the value, and keep giving the rest from the Release.

    La chiave è una foglia di values, che solo l’Aggregate scrive, quindi un Aggregate che dichiara una delle due associazioni e nomina la sua values.key lo evita: la Recipe compose dell’agente legge ciascun segreto sotto la chiave che la sua associazione nomina. Kubernetes non ha questo limite, perché lì ogni segreto è un riferimento a un Secret per nome e chiave dei dati anziché un valore consegnato sotto una chiave.

  • Una chiave nel percorso dell’indirizzo. Dove il server legge la propria chiave dal percorso anziché dalla query string, l’indirizzo dello strumento è l’indirizzo senza quella parte del percorso, e il Secret contiene l’indirizzo intero.

  • L’host è scritto due volte, in chiaro nell’indirizzo dello strumento e dentro il Secret, e nulla verifica che i due coincidano, perché il compilatore non legge mai un Secret.

Comporre l’indirizzo a runtime dalla sola chiave, con un riferimento $(VAR) in una variabile semplice, funziona solo su Kubernetes: Kubernetes espande un tale riferimento dalle voci elencate prima di esso nel container, e il provider helm elenca le voci che legge da un Secret prima delle variabili semplici, mentre Docker Compose non espande alcun riferimento $(VAR) tra le voci dell’ambiente di un servizio.

Adattarlo

  • Un server che verifica anche un header. Associa credential sulla stessa connessione. L’agente riceve MCP_CREDENTIAL_SEARCH e l’header sotto cui presentarla, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, a meno che la Release non indichi l’header proprio del server in infra.credential_header dello strumento. Su Docker Compose, nomina nell’Aggregate la chiave di una delle due, come sopra.
  • Più server. Cabla una connessione per server sul socket tools. Le variabili di ciascuna connessione portano il suo alias, e ciascuna connessione conserva i propri segreti.
  • Un server che legge la propria chiave solo da un header. Ometti endpoint, e MCP_URL_<ALIAS> è l’indirizzo che lo strumento pubblica.

Determinismo

Entrambe le Releases eseguono il build con --verify-determinism, che renderizza ogni nodo due volte e confronta i byte emessi:

Terminal window
aggrega build --release release-helm.yaml --verify-determinism

Ricostruire l’una o l’altra da un albero pulito ne riproduce l’output renderizzato byte per byte.

File

  • aggregate.yaml — lo strumento e l’agente, cablati tramite il socket tools, senza alcun segreto associato.
  • manifest-helm.yaml, manifest-compose.yaml — lo strumento su mcp-remote, l’agente sulla propria Recipe, e la Feature di credenziale che usa ciascuna destinazione.
  • release-helm.yaml, release-compose.yaml — l’indirizzo dello strumento senza la sua chiave, l’immagine dell’agente, e il segreto endpoint sulla connessione dell’agente.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — l’agente: il suo socket tools con gli slot credential ed endpoint.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — l’agente su ciascuna destinazione.
  • .aggrega-config.yaml — lo stack di ricerca del catalogo e il registry.
  • build-release.sh — esegue il build di una Release, mostrando il comando aggrega build equivalente.

Per una chiave che l’agente presenta in un header, conservata sulla connessione su cui viene presentata, vedi connection-credentials. Il modello alla base di entrambi è il Modello delle credenziali, e le realizzazioni dello strumento sono descritte con l’etichetta di trasporto dello strumento in Features di IA.