Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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

instanciaComponent del catálogoqué es aquí
searchcore/ai-tool/mcpun servidor Model Context Protocol que gestiona otra persona, asignado a mcp-remote, que no ejecuta nada
agentlocal/ai-agent/mcp-clientel agente, conectado a search a través de su socket tools

Dos Releases comparten el único Aggregate, cada una con un Manifest propio:

ReleaseManifestdestinode dónde viene la dirección completa
release-helm.yamlmanifest-helm.yamlKubernetesun Secret que el namespace ya contiene: core/referenced-secret enlazado con helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeuna 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:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd mcp-address-from-secret

Compilación

Terminal window
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>/dist

La 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/mcp

helm/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: 443

Así 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-address

Una 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:

Terminal window
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.com

MCP_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 el secretKeyRef de arriba, leyendo el nombre y la clave de datos del Secret de lo que publica helm/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-value que 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 un endpoint como un credential a search imprime:

    [… 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 clave es una hoja de values, que solo escribe el Aggregate, así que un Aggregate que declara una de las dos vinculaciones y nombra su values.key lo 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 credential en la misma conexión. El agente recibe MCP_CREDENTIAL_SEARCH y la cabecera bajo la que presentarla, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, a menos que la Release nombre la cabecera propia del servidor en infra.credential_header de 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, y MCP_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:

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

Recompilar 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 socket tools, sin ningún secreto vinculado.
  • manifest-helm.yaml, manifest-compose.yaml — la herramienta a mcp-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 secreto endpoint en la conexión del agente.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — el agente: su socket tools con los slots credential y endpoint.
  • 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 comando aggrega build equivalente.

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.