Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

L’adresse d’un outil à partir d’un Secret — un serveur Model Context Protocol qui lit sa clé dans son adresse

Certains serveurs Model Context Protocol exploités par quelqu’un d’autre lisent leur clé dans leur propre adresse — https://mcp.example.com/mcp?api_key=<key> — plutôt que dans un en-tête de requête. Une telle adresse ne peut pas être écrite dans l’outil comme une adresse ordinaire : l’outil publie son adresse telle qu’elle est écrite, de sorte que la clé atteindrait chaque fichier qu’atteint l’adresse.

Cet espace de travail conserve l’adresse en deux parties. L’outil, core/ai-tool/mcp, contient l’adresse sans la partie qui porte la clé. La connexion de l’agent à l’outil contient l’adresse entière sous forme de secret, et la Release indique où il se trouve. Il se construit pour Kubernetes et pour Docker Compose, et sur les deux aucun fichier rendu ne porte la clé.

L’agent est déclaré dans le catalogue propre de cet espace de travail, si bien que le socket qui contient l’adresse est écrit ici en entier. Les runtimes d’agents de la bibliothèque standard core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk et mastra, et les plateformes core/ai-agent/flowise et n8n, déclarent un socket tools avec les deux mêmes slots. L’outil, les deux Features d’informations d’identification et leurs réalisations sont livrés dans le catalogue de la bibliothèque standard.

Ce qu’il construit

instanceComponent du cataloguece qu’il est ici
searchcore/ai-tool/mcpun serveur Model Context Protocol exploité par quelqu’un d’autre, mappé sur mcp-remote, qui n’exécute rien
agentlocal/ai-agent/mcp-clientl’agent, câblé à search par son socket tools

Deux Releases partagent l’unique Aggregate, chacune avec un Manifest qui lui est propre :

ReleaseManifestcibled’où vient l’adresse entière
release-helm.yamlmanifest-helm.yamlKubernetesun Secret que le namespace contient déjà : core/referenced-secret lié à helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeune référence de variable Compose : core/secret-value lié à compose/dotenv-secret

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

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

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

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/

Chaque Release écrit dans son propre répertoire, de sorte que les deux arborescences rendues coexistent et peuvent être comparées côte à côte.

.aggrega-config.yaml liste le catalog/ propre de cet espace de travail, qui contient l’agent et ses deux Recipes ; tout le reste se résout depuis hub.aggrega.ai, le registre par défaut qu’il nomme. Avec une copie de travail du catalogue de la bibliothèque standard (où en obtenir une) nommée avec --catalog, chaque entité se résout depuis ces deux répertoires, si bien que le build aboutit aussi avec --offline, qui refuse tout accès au réseau. --auto-pull écrit le fichier de verrouillage de chaque Release pendant le build ; les fichiers de verrouillage et la sortie rendue sont générés, pas livrés.

Le build Kubernetes affiche, <workspace> désignant le dossier de cet exemple :

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

Le build compose affiche les mêmes lignes pour release-compose.yaml, son avertissement nommant core/secret-value, et écrit un fichier. La ligne notice: porte sur la Feature d’informations d’identification que rattache la Release : elle accepte le localisateur du secret, origin, depuis les values du développeur ou l’infra de l’opérateur, et l’avertissement signale qu’une feuille est déclarée dans les deux piliers. Il ne change aucun verdict ni aucun octet rendu.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `mcp-address-from-secret`, appelez une fois l’outil `scaffold` avec `example` défini sur `mcp-address-from-secret` et sans `dir` : il écrit l’exemple dans un nouveau dossier `mcp-address-from-secret`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-helm.yaml` et `release-compose.yaml` —, chaque fois avec `workspace_root` défini sur `mcp-address-from-secret`, `release` défini sur ce fichier, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `mcp-address-from-secret/dist/`.

L’outil contient l’adresse sans sa clé

Extrait de release-helm.yaml :

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

helm/mcp-remote lit dans cette adresse l’hôte, le port et le schéma qu’il publie, et émet un fichier pour l’outil : un Service ExternalName qui fait correspondre un nom interne au cluster à l’hôte. Le spec entier de dist/kubernetes/helm/search-service.yaml :

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

L’adresse que contient l’outil a donc besoin au moins d’un schéma et d’un hôte, et ne contient rien de la partie qui porte la clé. compose/mcp-remote ne définit aucun service pour l’outil.

La connexion de l’agent contient l’adresse entière

Le Component de l’agent déclare deux slots de secret sur son socket tools. Extrait de catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, sans les descriptions :

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 contient une clé que l’agent présente dans un en-tête de requête ; endpoint contient l’adresse entière, pour un serveur qui lit sa clé dans l’adresse elle-même. unauthenticated est la déclaration propre à la connexion que son outil ne prend aucune information d’identification, et ne change rien à ce que rend l’agent. Les trois se trouvent sur la connexion, de sorte qu’un agent qui atteint plusieurs serveurs porte le secret de chaque serveur sur la connexion de ce serveur.

La Release remplit endpoint sur la connexion que l’Aggregate a câblée. Extrait de release-helm.yaml :

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

Une Release n’écrit aucun values, donc origin se trouve dans infra, et la clé de données lue dans le Secret est celle par défaut de la Feature, value. Le Manifest lie core/referenced-secret à helm/k8s-existing-secret, qui lit origin comme le nom d’un Secret que le namespace contient déjà et ne rend rien. Le Secret est créé en dehors de la Release, par la personne qui la déploie :

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

Le conteneur de l’agent y lit l’adresse. L’env de 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 est l’adresse entière, lue dans le Secret par nom et par clé de données ; MCP_HOST_SEARCH est l’hôte que publie l’outil. dist/kubernetes/helm/ contient le Deployment de l’agent et le Service de l’outil, et rien d’autre : aucun Secret n’est rendu, et aucun fichier ne porte la clé.

Sur Docker Compose

Compose n’a pas de référence de secret, donc la Release compose remplit le même slot avec core/secret-value, dont l’origine est une référence de variable Compose. Extrait de release-compose.yaml :

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

compose/dotenv-secret livre la référence telle qu’elle est écrite, et le service de l’agent la porte. L’environment du service agent dans dist/local/compose/docker-compose.yaml, qui définit ce service et aucun autre :

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

Docker Compose substitue SEARCH_MCP_URL au démarrage de la stack — depuis l’environnement du shell, un fichier nommé avec --env-file ou le fichier .env du répertoire du projet — si bien que le fichier ne porte que la référence.

Comment les Recipes de l’agent lisent le slot

Chaque connexion sur le socket tools devient des variables d’environnement nommées d’après l’alias de la connexion en majuscules : MCP_HOST_<ALIAS> à partir de l’hôte que publie l’outil, et MCP_URL_<ALIAS> à partir de l’adresse que publie l’outil — sauf si la connexion porte un secret endpoint, auquel cas MCP_URL_<ALIAS> est ce secret et l’adresse publiée n’est pas livrée du tout. Une connexion qui porte un credential ajoute MCP_CREDENTIAL_<ALIAS> et MCP_CREDENTIAL_HEADER_<ALIAS>, l’en-tête de requête sous lequel l’outil indique de la présenter.

  • Sur Kubernetes, le secret est une entrée de rattachement nommant la connexion et le slot — connection: search, from: endpoint, as: env — que le fournisseur transforme en secretKeyRef ci-dessus, en lisant le nom et la clé de données du Secret dans ce que publie helm/k8s-existing-secret.
  • Sur Docker Compose, le secret arrive sur le canal d’injection de l’agent sous la clé sous laquelle son propre rattachement l’a livré, values.key, et la Recipe écrit cette valeur dans l’environnement du service.

Si elle est plutôt écrite dans l’infra.endpoint de l’outil, la clé va partout où va l’adresse publiée : le MCP_URL_SEARCH de l’agent la porte comme valeur littérale, dans le Deployment sur Kubernetes et dans l’environnement du service dans le fichier Compose, car la réalisation de référence publie l’adresse telle qu’elle est écrite.

Limites

  • Sur Docker Compose, deux secrets que la Release seule rattache à un même agent entrent en collision. Chaque rattachement core/secret-value que fait une Release livre sous la clé par défaut de la Feature, value, donc un second sur le même agent — l’adresse d’un autre serveur, ou une information d’identification à côté de celle-ci — arrête le build. Une Release qui rattache à la fois un endpoint et un credential à search affiche :

    [… 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 clé est une feuille de values, que seul l’Aggregate écrit, donc un Aggregate qui déclare l’un des deux rattachements et nomme sa values.key l’évite : la Recipe compose de l’agent lit chaque secret sous la clé que nomme son propre rattachement. Kubernetes n’a pas cette limite, car chaque secret y est une référence à un Secret par nom et par clé de données plutôt qu’une valeur livrée sous une clé.

  • Une clé dans le chemin de l’adresse. Lorsque le serveur lit sa clé dans le chemin plutôt que dans la chaîne de requête, l’adresse de l’outil est l’adresse sans cette partie du chemin, et le Secret contient l’adresse entière.

  • L’hôte est écrit deux fois, en clair dans l’adresse de l’outil et dans le Secret, et rien ne vérifie que les deux concordent, car le compilateur ne lit jamais un Secret.

Assembler l’adresse à l’exécution à partir de la seule clé, avec une référence $(VAR) dans une variable simple, ne fonctionne que sur Kubernetes : Kubernetes développe une telle référence à partir des entrées listées avant elle dans le conteneur, et le fournisseur helm liste les entrées qu’il lit dans un Secret avant les variables simples, tandis que Docker Compose ne développe aucune référence $(VAR) entre les entrées d’environnement d’un service.

L’adapter

  • Un serveur qui vérifie aussi un en-tête. Rattachez credential sur la même connexion. L’agent reçoit MCP_CREDENTIAL_SEARCH et l’en-tête sous lequel les présenter, MCP_CREDENTIAL_HEADER_SEARCH : Authorization, sauf si la Release nomme l’en-tête propre au serveur dans infra.credential_header de l’outil. Sur Docker Compose, nommez dans l’Aggregate la clé de l’un des deux, comme ci-dessus.
  • Plusieurs serveurs. Câblez une connexion par serveur sur le socket tools. Les variables de chaque connexion portent son alias, et chaque connexion porte ses propres secrets.
  • Un serveur qui lit sa clé uniquement dans un en-tête. Omettez endpoint, et MCP_URL_<ALIAS> est l’adresse que publie l’outil.

Déterminisme

Les deux Releases se construisent sous --verify-determinism, qui rend chaque nœud deux fois et compare les octets émis :

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

Reconstruire l’une ou l’autre à partir d’une arborescence propre reproduit sa sortie rendue octet pour octet.

Fichiers

  • aggregate.yaml — l’outil et l’agent, câblés via le socket tools, sans aucun secret rattaché.
  • manifest-helm.yaml, manifest-compose.yaml — l’outil vers mcp-remote, l’agent vers sa propre Recipe, et la Feature d’informations d’identification qu’utilise chaque cible.
  • release-helm.yaml, release-compose.yaml — l’adresse de l’outil sans sa clé, l’image de l’agent, et le secret endpoint sur la connexion de l’agent.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — l’agent : son socket tools avec les slots credential et endpoint.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — l’agent sur chaque cible.
  • .aggrega-config.yaml — la pile de recherche du catalogue et le registre.
  • build-release.sh — construit une Release, en affichant la commande aggrega build équivalente.

Pour une clé que l’agent présente dans un en-tête, portée sur la connexion sur laquelle elle est présentée, voir connection-credentials. Le modèle qui sous-tend les deux est le Modèle des informations d’identification, et les réalisations de l’outil sont décrites avec le label de transport d’outil dans Features d’IA.