La dirección de una herramienta a partir de un Secret — un servidor Model Context Protocol que lee su clave de su dirección
Algunos servidores Model Context Protocol que gestiona otra persona leen su clave de su propia dirección — https://mcp.example.com/mcp?api_key=<key> — en lugar de una cabecera de solicitud. Una dirección así no puede escribirse en la herramienta como una ordinaria: la herramienta publica su dirección tal como está escrita, así que la clave llegaría a cada archivo al que llega la dirección.
Este espacio de trabajo guarda la dirección en dos partes. La herramienta, core/ai-tool/mcp, guarda la dirección sin la parte que lleva la clave. La conexión del agente con la herramienta guarda la dirección completa como un secreto, y la Release nombra dónde se encuentra. Se compila para Kubernetes y para Docker Compose, y en ambos ningún archivo renderizado lleva la clave.
El agente se declara en el propio catálogo de este espacio de trabajo, así que el socket que guarda la dirección se escribe aquí completo. Los runtimes de agentes de la biblioteca estándar core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk y mastra, y las plataformas core/ai-agent/flowise y n8n, declaran un socket tools con los mismos dos slots. La herramienta, las dos Features de credenciales y sus realizaciones se incluyen en el catálogo de la biblioteca estándar.
Lo que construye
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
search | core/ai-tool/mcp | un servidor Model Context Protocol que gestiona otra persona, asignado a mcp-remote, que no ejecuta nada |
agent | local/ai-agent/mcp-client | el agente, conectado a search a través de su socket tools |
Dos Releases comparten el único Aggregate, cada una con un Manifest propio:
| Release | Manifest | destino | de dónde viene la dirección completa |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | un Secret que el namespace ya contiene: core/referenced-secret enlazado con helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | una referencia a una variable de Compose: core/secret-value enlazado con compose/dotenv-secret |
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example mcp-address-from-secretDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd mcp-address-from-secretCompilación
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/Cada Release escribe en su propio directorio, así que los dos árboles renderizados coexisten y pueden compararse uno al lado del otro.
.aggrega-config.yaml lista el catalog/ propio de este espacio de trabajo, que contiene el agente y sus dos Recipes; todo lo demás se resuelve desde hub.aggrega.ai, el registro predeterminado que nombra. Con una copia de trabajo del catálogo de la biblioteca estándar (dónde conseguir una) indicada con --catalog, cada entidad se resuelve desde esos dos directorios, así que la compilación también se completa con --offline, que rechaza todo acceso a la red. --auto-pull escribe el archivo de bloqueo de cada Release durante la compilación; los archivos de bloqueo y la salida renderizada se generan, no se distribuyen.
La compilación para Kubernetes imprime, con <workspace> en lugar de la carpeta de este ejemplo:
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>/distLa compilación para compose imprime las mismas líneas para release-compose.yaml, con su aviso nombrando core/secret-value, y escribe un archivo. La línea notice: trata sobre la Feature de credencial que vincula la Release: acepta el localizador del secreto, origin, de los values del desarrollador o de la infra del operador, y el aviso informa de que una hoja está declarada en ambos pilares. No cambia ningún veredicto ni ningún byte renderizado.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `mcp-address-from-secret`, llama una vez a la herramienta `scaffold` con `example` establecido en `mcp-address-from-secret` y sin `dir`: escribe el ejemplo en una nueva carpeta `mcp-address-from-secret`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-helm.yaml` y `release-compose.yaml` —, cada vez con `workspace_root` establecido en `mcp-address-from-secret`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `mcp-address-from-secret/dist/`.La herramienta guarda la dirección sin su clave
De release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote lee de esa dirección el host, el puerto y el esquema que publica, y emite un archivo para la herramienta: un Service ExternalName que asigna un nombre interno del clúster al host. El spec completo de dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Así que la dirección que guarda la herramienta necesita al menos un esquema y un host, y no guarda nada de la parte que lleva la clave. compose/mcp-remote no define ningún servicio para la herramienta.
La conexión del agente guarda la dirección completa
El Component del agente declara dos slots de secreto en su socket tools. De catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, sin las descripciones:
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 guarda una clave que el agente presenta en una cabecera de solicitud; endpoint guarda la dirección completa, para un servidor que lee su clave de la propia dirección. unauthenticated es la declaración propia de la conexión de que su herramienta no requiere ninguna credencial, y no cambia nada de lo que renderiza el agente. Los tres están en la conexión, así que un agente que llega a varios servidores guarda el secreto de cada servidor en la conexión de ese servidor.
La Release rellena endpoint en la conexión que conectó el Aggregate. De release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressUna Release no escribe values, así que origin está en infra, y la clave de datos que se lee del Secret es la predeterminada de la Feature, value. El Manifest enlaza core/referenced-secret con helm/k8s-existing-secret, que lee origin como el nombre de un Secret que el namespace ya contiene y no renderiza nada. El Secret se crea fuera de la Release, por quien la despliega:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'El contenedor del agente lee la dirección de él. El 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.comMCP_URL_SEARCH es la dirección completa, leída del Secret por nombre y clave de datos; MCP_HOST_SEARCH es el host que publica la herramienta. dist/kubernetes/helm/ contiene el Deployment del agente y el Service de la herramienta y nada más: no se renderiza ningún Secret, y ningún archivo lleva la clave.
En Docker Compose
Compose no tiene referencias a secretos, así que la Release de compose rellena el mismo slot con core/secret-value, con una referencia a una variable de Compose como origen. De release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret entrega la referencia tal como está escrita, y el servicio del agente la lleva. El environment del servicio agent en dist/local/compose/docker-compose.yaml, que define ese servicio y ningún otro:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose sustituye SEARCH_MCP_URL cuando se inicia el stack — desde el entorno del shell, un archivo indicado con --env-file o el archivo .env del directorio del proyecto — así que el archivo solo lleva la referencia.
Cómo leen el slot las Recipes del agente
Cada conexión en el socket tools se convierte en variables de entorno con el nombre del alias de la conexión en mayúsculas: MCP_HOST_<ALIAS> a partir del host que publica la herramienta, y MCP_URL_<ALIAS> a partir de la dirección que publica la herramienta — a menos que la conexión lleve un secreto endpoint, en cuyo caso MCP_URL_<ALIAS> es ese secreto y la dirección publicada no se entrega en absoluto. Una conexión que lleva un credential añade MCP_CREDENTIAL_<ALIAS> y MCP_CREDENTIAL_HEADER_<ALIAS>, la cabecera de solicitud que la herramienta publica para presentarla.
- En Kubernetes el secreto es una entrada de vinculación que nombra la conexión y el slot —
connection: search,from: endpoint,as: env— que el proveedor convierte en elsecretKeyRefde arriba, leyendo el nombre y la clave de datos del Secret de lo que publicahelm/k8s-existing-secret. - En Docker Compose el secreto llega al canal de inyección del agente bajo la clave con la que lo entregó su propia vinculación,
values.key, y la Recipe escribe ese valor en el entorno del servicio.
Si en cambio se escribe en el infra.endpoint de la herramienta, la clave va a todas partes adonde va la dirección publicada: el MCP_URL_SEARCH del agente la lleva como valor literal, en el Deployment en Kubernetes y en el entorno del servicio en el archivo de Compose, porque la realización de referencia publica la dirección tal como está escrita.
Limitaciones
-
En Docker Compose, dos secretos que solo la Release vincula a un mismo agente colisionan. Cada vinculación
core/secret-valueque hace una Release entrega bajo la clave predeterminada de la Feature,value, así que una segunda en el mismo agente — la dirección de otro servidor, o una credencial junto a esta — detiene la compilación. Una Release que vincula tanto unendpointcomo uncredentialasearchimprime:[… 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.La clave es una hoja de
values, que solo escribe el Aggregate, así que un Aggregate que declara una de las dos vinculaciones y nombra suvalues.keylo evita: la Recipe de compose del agente lee cada secreto bajo la clave que nombra su propia vinculación. Kubernetes no tiene esa limitación, porque allí cada secreto es una referencia a un Secret por nombre y clave de datos en lugar de un valor entregado bajo una clave. -
Una clave en la ruta de la dirección. Cuando el servidor lee su clave de la ruta en lugar de la cadena de consulta, la dirección de la herramienta es la dirección sin esa parte de la ruta, y el Secret guarda la dirección completa.
-
El host se escribe dos veces, en claro en la dirección de la herramienta y dentro del Secret, y nada comprueba que ambos coincidan, porque el compilador nunca lee un Secret.
Ensamblar la dirección en tiempo de ejecución a partir de la clave sola, con una referencia $(VAR) en una variable simple, solo funciona en Kubernetes: Kubernetes expande una referencia así a partir de las entradas listadas antes de ella en el contenedor, y el proveedor helm lista las entradas que lee de un Secret antes de las variables simples, mientras que Docker Compose no expande ninguna referencia $(VAR) entre las entradas de entorno de un servicio.
Adaptarlo
- Un servidor que además comprueba una cabecera. Vincula
credentialen la misma conexión. El agente recibeMCP_CREDENTIAL_SEARCHy la cabecera bajo la que presentarla,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, a menos que la Release nombre la cabecera propia del servidor eninfra.credential_headerde la herramienta. En Docker Compose, nombra en el Aggregate la clave de una de las dos, como arriba. - Varios servidores. Establece una conexión por servidor en el socket
tools. Las variables de cada conexión llevan su alias, y cada conexión guarda sus propios secretos. - Un servidor que lee su clave solo de una cabecera. Omite
endpoint, yMCP_URL_<ALIAS>es la dirección que publica la herramienta.
Determinismo
Ambas Releases se compilan con --verify-determinism, que renderiza cada nodo dos veces y compara los bytes emitidos:
aggrega build --release release-helm.yaml --verify-determinismRecompilar cualquiera de las dos desde un árbol limpio reproduce su salida renderizada byte a byte.
Archivos
aggregate.yaml— la herramienta y el agente, conectados a través del sockettools, sin ningún secreto vinculado.manifest-helm.yaml,manifest-compose.yaml— la herramienta amcp-remote, el agente a su propia Recipe, y la Feature de credencial que usa cada destino.release-helm.yaml,release-compose.yaml— la dirección de la herramienta sin su clave, la imagen del agente, y el secretoendpointen la conexión del agente.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— el agente: su sockettoolscon los slotscredentialyendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— el agente en cada destino..aggrega-config.yaml— la pila de búsqueda del catálogo y el registro.build-release.sh— compila una Release, mostrando el comandoaggrega buildequivalente.
Para una clave que el agente presenta en una cabecera, guardada en la conexión en la que se presenta, consulta connection-credentials. El modelo detrás de ambos es el Modelo de credenciales, y las realizaciones de la herramienta se describen con la etiqueta de transporte de herramienta en Features de IA.