Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Die Adresse eines Tools aus einem Secret — ein Model-Context-Protocol-Server, der seinen Schlüssel aus seiner Adresse liest

Manche Model-Context-Protocol-Server, die jemand anderes betreibt, lesen ihren Schlüssel aus ihrer eigenen Adresse — https://mcp.example.com/mcp?api_key=<key> — statt aus einem Request-Header. Eine solche Adresse kann nicht wie eine gewöhnliche in das Tool geschrieben werden: Das Tool veröffentlicht seine Adresse so, wie sie geschrieben ist, sodass der Schlüssel jede Datei erreichen würde, die die Adresse erreicht.

Dieser Workspace hält die Adresse in zwei Teilen. Das Tool, core/ai-tool/mcp, hält die Adresse ohne den Teil, der den Schlüssel trägt. Die Verbindung des Agenten zum Tool hält die ganze Adresse als Secret, und das Release nennt, wo es liegt. Er lässt sich für Kubernetes und für Docker Compose bauen, und auf beiden trägt keine gerenderte Datei den Schlüssel.

Der Agent ist im eigenen Katalog dieses Workspace deklariert, daher ist der Socket, der die Adresse hält, hier vollständig ausgeschrieben. Die Agent-Runtimes der Standardbibliothek core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk und mastra sowie die Plattformen core/ai-agent/flowise und n8n deklarieren einen Socket tools mit denselben zwei Slots. Das Tool, die zwei Zugangsdaten-Features und ihre Realisierungen werden im Katalog der Standardbibliothek ausgeliefert.

Was es baut

InstanzKatalog-Componentwas es hier ist
searchcore/ai-tool/mcpein Model-Context-Protocol-Server, den jemand anderes betreibt, mcp-remote zugeordnet, das nichts ausführt
agentlocal/ai-agent/mcp-clientder Agent, über seinen Socket tools mit search verdrahtet

Zwei Releases teilen sich das eine Aggregate, jedes mit einem eigenen Manifest:

ReleaseManifestZielwoher die ganze Adresse kommt
release-helm.yamlmanifest-helm.yamlKubernetesein Secret, das der Namespace bereits enthält: core/referenced-secret an helm/k8s-existing-secret gebunden
release-compose.yamlmanifest-compose.yamlDocker Composeeine Compose-Variablenreferenz: core/secret-value an compose/dotenv-secret gebunden

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

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/

Jedes Release schreibt in sein eigenes Verzeichnis, sodass die beiden gerenderten Bäume nebeneinander bestehen und direkt verglichen werden können.

.aggrega-config.yaml listet den eigenen catalog/ dieses Workspace auf, der den Agenten und seine zwei Recipes enthält; alles andere wird aus hub.aggrega.ai aufgelöst, der Standard-Registry, die sie nennt. Mit einem Checkout des Katalogs der Standardbibliothek (woher Sie einen bekommen), der mit --catalog angegeben wird, wird jede Entität aus diesen beiden Verzeichnissen aufgelöst, sodass der Build auch mit --offline abgeschlossen wird, das jeden Netzwerkzugriff zurückweist. --auto-pull schreibt während des Builds das Lockfile jedes Release; Lockfiles und die gerenderte Ausgabe werden erzeugt, nicht ausgeliefert.

Der Kubernetes-Build gibt Folgendes aus, wobei <workspace> für den Ordner dieses Beispiels steht:

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

Der compose-Build gibt dieselben Zeilen für release-compose.yaml aus, wobei sein Hinweis core/secret-value nennt, und schreibt eine Datei. Die Zeile notice: betrifft das Zugangsdaten-Feature, das das Release anbindet: Es nimmt den Locator des Secrets, origin, aus den values des Entwicklers oder der infra des Betreibers an, und der Hinweis meldet, dass ein Blatt in beiden Säulen deklariert ist. Er ändert kein Verdikt und kein gerendertes Byte.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `mcp-address-from-secret` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `mcp-address-from-secret` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `mcp-address-from-secret`. Rufen Sie anschließend das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-helm.yaml` und `release-compose.yaml` —, jedes Mal mit `workspace_root` auf `mcp-address-from-secret`, `release` auf diese Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir, welche Dateien jeder Build geschrieben hat; sie liegen unter `mcp-address-from-secret/dist/`.

Das Tool hält die Adresse ohne ihren Schlüssel

Aus release-helm.yaml:

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

helm/mcp-remote liest den Host, den Port und das Schema, die es veröffentlicht, aus dieser Adresse und gibt eine Datei für das Tool aus: einen Service ExternalName, der einen clusterinternen Namen auf den Host abbildet. Die vollständige spec von dist/kubernetes/helm/search-service.yaml:

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

Die Adresse, die das Tool hält, braucht also mindestens ein Schema und einen Host und enthält nichts von dem Teil, der den Schlüssel trägt. compose/mcp-remote definiert überhaupt keinen Service für das Tool.

Die Verbindung des Agenten hält die ganze Adresse

Die Component des Agenten deklariert an ihrem Socket tools zwei Secret-Slots. Aus catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, ohne die Beschreibungen:

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 hält einen Schlüssel, den der Agent in einem Request-Header vorlegt; endpoint hält die ganze Adresse, für einen Server, der seinen Schlüssel aus der Adresse selbst liest. unauthenticated ist die eigene Aussage der Verbindung, dass ihr Tool keine Zugangsdaten verlangt, und ändert nichts an dem, was der Agent rendert. Alle drei sitzen an der Verbindung, sodass ein Agent, der mehrere Server erreicht, das Secret jedes Servers an der Verbindung dieses Servers hält.

Das Release füllt endpoint an der Verbindung, die das Aggregate verdrahtet hat. Aus release-helm.yaml:

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

Ein Release schreibt keine values, daher steht origin in infra, und der aus dem Secret gelesene Datenschlüssel ist der Standardwert des Feature, value. Das Manifest bindet core/referenced-secret an helm/k8s-existing-secret, das origin als Namen eines Secrets liest, das der Namespace bereits enthält, und nichts rendert. Das Secret wird außerhalb des Release angelegt, von dem, der es bereitstellt:

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

Der Container des Agenten liest die Adresse daraus. Das env von 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 ist die ganze Adresse, aus dem Secret über Name und Datenschlüssel gelesen; MCP_HOST_SEARCH ist der Host, den das Tool veröffentlicht. dist/kubernetes/helm/ enthält das Deployment des Agenten und den Service des Tools und sonst nichts: Kein Secret wird gerendert, und keine Datei trägt den Schlüssel.

Auf Docker Compose

Compose hat keine Secret-Referenz, daher füllt das compose-Release denselben Slot mit core/secret-value, mit einer Compose-Variablenreferenz als Ursprung. Aus release-compose.yaml:

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

compose/dotenv-secret stellt die Referenz so zu, wie sie geschrieben ist, und der Service des Agenten trägt sie. Das environment des Service agent in dist/local/compose/docker-compose.yaml, die diesen Service und keinen anderen definiert:

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

Docker Compose ersetzt SEARCH_MCP_URL beim Start des Stacks — aus der Shell-Umgebung, aus einer mit --env-file angegebenen Datei oder aus der Datei .env im Projektverzeichnis —, sodass die Datei nur die Referenz trägt.

Wie die Recipes des Agenten den Slot lesen

Jede Verbindung am Socket tools wird zu Umgebungsvariablen, die nach dem Alias der Verbindung in Großbuchstaben benannt sind: MCP_HOST_<ALIAS> aus dem Host, den das Tool veröffentlicht, und MCP_URL_<ALIAS> aus der Adresse, die das Tool veröffentlicht — es sei denn, die Verbindung trägt ein Secret endpoint; in diesem Fall ist MCP_URL_<ALIAS> dieses Secret, und die veröffentlichte Adresse wird überhaupt nicht zugestellt. Eine Verbindung mit einem credential fügt MCP_CREDENTIAL_<ALIAS> hinzu sowie MCP_CREDENTIAL_HEADER_<ALIAS>, den Request-Header, unter dem es laut der Veröffentlichung des Tools vorzulegen ist.

  • Auf Kubernetes ist das Secret ein Anbindungseintrag, der die Verbindung und den Slot nennt — connection: search, from: endpoint, as: env —, den der Provider in die obige secretKeyRef umwandelt, wobei er den Namen und den Datenschlüssel des Secrets aus dem liest, was helm/k8s-existing-secret veröffentlicht.
  • Auf Docker Compose kommt das Secret im Inject-Kanal des Agenten unter dem Schlüssel an, unter dem seine eigene Anbindung es zugestellt hat, values.key, und das Recipe schreibt diesen Wert in die Umgebung des Service.

Wird der Schlüssel stattdessen in die infra.endpoint des Tools geschrieben, gelangt er überall dorthin, wohin die veröffentlichte Adresse gelangt: Die MCP_URL_SEARCH des Agenten trägt ihn als literalen Wert, im Deployment auf Kubernetes und in der Umgebung des Service in der Compose-Datei, weil die Referenz-Realisierung die Adresse so veröffentlicht, wie sie geschrieben ist.

Einschränkungen

  • Auf Docker Compose kollidieren zwei Secrets, die allein das Release an einen Agenten anbindet. Jede Anbindung core/secret-value, die ein Release vornimmt, stellt unter dem Standardschlüssel des Feature, value, zu, sodass eine zweite am selben Agenten — die Adresse eines anderen Servers oder Zugangsdaten neben diesen — den Build abbricht. Ein Release, das sowohl ein endpoint als auch ein credential an search anbindet, gibt aus:

    [… 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.

    Der Schlüssel ist ein Blatt von values, das nur das Aggregate schreibt, daher vermeidet ein Aggregate es, das eine der beiden Anbindungen deklariert und ihren values.key nennt: Das compose-Recipe des Agenten liest jedes Secret unter dem Schlüssel, den seine eigene Anbindung nennt. Kubernetes hat keine solche Einschränkung, weil jedes Secret dort eine Referenz auf ein Secret über Name und Datenschlüssel ist und kein unter einem Schlüssel zugestellter Wert.

  • Ein Schlüssel im Pfad der Adresse. Wo der Server seinen Schlüssel aus dem Pfad statt aus dem Query-String liest, ist die Adresse des Tools die Adresse ohne diesen Teil des Pfads, und das Secret enthält sie ganz.

  • Der Host wird zweimal geschrieben, offen in der Adresse des Tools und im Secret, und nichts prüft, ob beide übereinstimmen, weil der Compiler nie ein Secret liest.

Die Adresse zur Laufzeit allein aus dem Schlüssel zusammenzusetzen, mit einer Referenz $(VAR) in einer einfachen Variablen, funktioniert nur auf Kubernetes: Kubernetes expandiert eine solche Referenz aus den Einträgen, die vor ihr im Container aufgeführt sind, und der helm-Provider führt die Einträge, die er aus einem Secret liest, vor den einfachen Variablen auf, während Docker Compose keine Referenz $(VAR) zwischen den Umgebungseinträgen eines Service expandiert.

Anpassen

  • Ein Server, der zusätzlich einen Header prüft. Binden Sie credential an derselben Verbindung an. Der Agent erhält MCP_CREDENTIAL_SEARCH und den Header, unter dem er sie vorlegt, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, es sei denn, das Release nennt den eigenen Header des Servers in infra.credential_header des Tools. Nennen Sie auf Docker Compose den Schlüssel einer der beiden im Aggregate, wie oben.
  • Mehrere Server. Verdrahten Sie eine Verbindung pro Server am Socket tools. Die Variablen jeder Verbindung tragen ihren Alias, und jede Verbindung hält ihre eigenen Secrets.
  • Ein Server, der seinen Schlüssel nur aus einem Header liest. Lassen Sie endpoint weg, und MCP_URL_<ALIAS> ist die Adresse, die das Tool veröffentlicht.

Determinismus

Beide Releases werden mit --verify-determinism gebaut, das jeden Knoten zweimal rendert und die ausgegebenen Bytes vergleicht:

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

Ein Neubau eines der beiden aus einem sauberen Baum reproduziert seine gerenderte Ausgabe Byte für Byte.

Dateien

  • aggregate.yaml — das Tool und der Agent, über den Socket tools verdrahtet, ohne angebundenes Secret.
  • manifest-helm.yaml, manifest-compose.yaml — das Tool auf mcp-remote, der Agent auf sein eigenes Recipe und das Zugangsdaten-Feature, das jedes Ziel verwendet.
  • release-helm.yaml, release-compose.yaml — die Adresse des Tools ohne ihren Schlüssel, das Image des Agenten und das Secret endpoint an der Verbindung des Agenten.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — der Agent: sein Socket tools mit den Slots credential und endpoint.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — der Agent auf jedem Ziel.
  • .aggrega-config.yaml — der Suchstapel des Katalogs und die Registry.
  • build-release.sh — baut ein Release und gibt dabei den entsprechenden aggrega build-Befehl aus.

Für einen Schlüssel, den der Agent in einem Header vorlegt und der an der Verbindung gehalten wird, an der er vorgelegt wird, siehe connection-credentials. Das Modell hinter beiden ist das Zugangsdatenmodell, und die Realisierungen des Tools werden mit dem Tool-Transport-Label in KI-Features beschrieben.