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
| Instanz | Katalog-Component | was es hier ist |
|---|---|---|
search | core/ai-tool/mcp | ein Model-Context-Protocol-Server, den jemand anderes betreibt, mcp-remote zugeordnet, das nichts ausführt |
agent | local/ai-agent/mcp-client | der Agent, über seinen Socket tools mit search verdrahtet |
Zwei Releases teilen sich das eine Aggregate, jedes mit einem eigenen Manifest:
| Release | Manifest | Ziel | woher die ganze Adresse kommt |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | ein Secret, das der Namespace bereits enthält: core/referenced-secret an helm/k8s-existing-secret gebunden |
release-compose.yaml | manifest-compose.yaml | Docker Compose | eine 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:
aggrega scaffold --example mcp-address-from-secretDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd mcp-address-from-secretBuild
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>/distDer 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/mcphelm/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: 443Die 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-addressEin 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:
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.comMCP_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 obigesecretKeyRefumwandelt, wobei er den Namen und den Datenschlüssel des Secrets aus dem liest, washelm/k8s-existing-secretverö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 einendpointals auch eincredentialansearchanbindet, 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.credentialduplicate 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 ihrenvalues.keynennt: 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
credentialan derselben Verbindung an. Der Agent erhältMCP_CREDENTIAL_SEARCHund den Header, unter dem er sie vorlegt,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, es sei denn, das Release nennt den eigenen Header des Servers ininfra.credential_headerdes 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
endpointweg, undMCP_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:
aggrega build --release release-helm.yaml --verify-determinismEin 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 Sockettoolsverdrahtet, ohne angebundenes Secret.manifest-helm.yaml,manifest-compose.yaml— das Tool aufmcp-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 Secretendpointan der Verbindung des Agenten.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— der Agent: sein Sockettoolsmit den Slotscredentialundendpoint.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 entsprechendenaggrega 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.