O endereço de uma ferramenta a partir de um Secret — um servidor Model Context Protocol que lê a sua chave do seu endereço
Alguns servidores Model Context Protocol operados por terceiros leem a sua chave do próprio endereço — https://mcp.example.com/mcp?api_key=<key> — em vez de um cabeçalho da requisição. Um endereço assim não pode ser escrito na ferramenta como um comum: a ferramenta publica o seu endereço como está escrito, então a chave chegaria a todo arquivo a que o endereço chega.
Este espaço de trabalho guarda o endereço em duas partes. A ferramenta, core/ai-tool/mcp, guarda o endereço sem a parte que carrega a chave. A conexão do agente com a ferramenta guarda o endereço inteiro como um segredo, e a Release nomeia onde ele fica. O build funciona para Kubernetes e para Docker Compose, e em ambos nenhum arquivo renderizado carrega a chave.
O agente é declarado no catálogo próprio deste espaço de trabalho, então o socket que guarda o endereço é escrito aqui por completo. Os runtimes de agentes da biblioteca padrão core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk e mastra, e as plataformas core/ai-agent/flowise e n8n, declaram um socket tools com os mesmos dois slots. A ferramenta, as duas Features de credenciais e as suas realizações vêm no catálogo da biblioteca padrão.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
search | core/ai-tool/mcp | um servidor Model Context Protocol operado por terceiros, mapeado para mcp-remote, que não executa nada |
agent | local/ai-agent/mcp-client | o agente, ligado a search por meio do seu socket tools |
Duas Releases compartilham o único Aggregate, cada uma com um Manifest próprio:
| Release | Manifest | destino | de onde vem o endereço inteiro |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | um Secret que o namespace já contém: core/referenced-secret associado a helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | uma referência a uma variável do Compose: core/secret-value associado a compose/dotenv-secret |
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example mcp-address-from-secretEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
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/Cada Release escreve no seu próprio diretório, então as duas árvores renderizadas coexistem e podem ser comparadas lado a lado.
.aggrega-config.yaml lista o catalog/ próprio deste espaço de trabalho, que contém o agente e as suas duas Recipes; todo o resto é resolvido a partir de hub.aggrega.ai, o registro padrão que ele nomeia. Com um checkout do catálogo da biblioteca padrão (onde obter um) informado com --catalog, cada entidade é resolvida a partir desses dois diretórios, então o build também é concluído com --offline, que recusa todo acesso à rede. --auto-pull escreve o arquivo de bloqueio de cada Release durante o build; os arquivos de bloqueio e a saída renderizada são gerados, não distribuídos.
O build para Kubernetes imprime, com <workspace> no lugar da pasta deste exemplo:
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>/distO build para compose imprime as mesmas linhas para release-compose.yaml, com o seu aviso nomeando core/secret-value, e escreve um arquivo. A linha notice: diz respeito à Feature de credencial que a Release vincula: ela aceita o localizador do segredo, origin, dos values do desenvolvedor ou da infra do operador, e o aviso relata que uma folha está declarada nos dois pilares. Ele não muda nenhum veredito nem nenhum byte renderizado.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `mcp-address-from-secret`, chame a ferramenta `scaffold` uma vez com `example` definido como `mcp-address-from-secret` e sem `dir`: ela grava o exemplo em uma nova pasta `mcp-address-from-secret`. Depois chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-helm.yaml` e `release-compose.yaml` —, cada vez com `workspace_root` definido como `mcp-address-from-secret`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `mcp-address-from-secret/dist/`.A ferramenta guarda o endereço sem a sua chave
De release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote lê desse endereço o host, a porta e o esquema que publica, e emite um arquivo para a ferramenta: um Service ExternalName que mapeia um nome interno do cluster para o host. O spec inteiro de dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Portanto, o endereço que a ferramenta guarda precisa de pelo menos um esquema e um host, e não guarda nada da parte que carrega a chave. compose/mcp-remote não define nenhum serviço para a ferramenta.
A conexão do agente guarda o endereço inteiro
O Component do agente declara dois slots de segredo no seu socket tools. De catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, sem as descrições:
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 uma chave que o agente apresenta em um cabeçalho da requisição; endpoint guarda o endereço inteiro, para um servidor que lê a sua chave do próprio endereço. unauthenticated é a declaração da própria conexão de que a sua ferramenta não exige credencial, e não muda nada do que o agente renderiza. Os três ficam na conexão, então um agente que alcança vários servidores guarda o segredo de cada servidor na conexão desse servidor.
A Release preenche endpoint na conexão que o Aggregate ligou. De release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressUma Release não escreve values, então origin fica em infra, e a chave de dados lida do Secret é a padrão da Feature, value. O Manifest associa core/referenced-secret a helm/k8s-existing-secret, que lê origin como o nome de um Secret que o namespace já contém e não renderiza nada. O Secret é criado fora da Release, por quem a implanta:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'O contêiner do agente lê o endereço dele. O 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 é o endereço inteiro, lido do Secret por nome e chave de dados; MCP_HOST_SEARCH é o host que a ferramenta publica. dist/kubernetes/helm/ contém o Deployment do agente e o Service da ferramenta e nada mais: nenhum Secret é renderizado, e nenhum arquivo carrega a chave.
No Docker Compose
O Compose não tem referência a segredos, então a Release de compose preenche o mesmo slot com core/secret-value, tendo como origem uma referência a uma variável do Compose. De release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret entrega a referência como está escrita, e o serviço do agente a carrega. O environment do serviço agent em dist/local/compose/docker-compose.yaml, que define esse serviço e nenhum outro:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}O Docker Compose substitui SEARCH_MCP_URL quando a stack inicia — a partir do ambiente do shell, de um arquivo informado com --env-file ou do arquivo .env no diretório do projeto — então o arquivo carrega apenas a referência.
Como as Recipes do agente leem o slot
Cada conexão no socket tools vira variáveis de ambiente nomeadas com o alias da conexão em maiúsculas: MCP_HOST_<ALIAS> a partir do host que a ferramenta publica, e MCP_URL_<ALIAS> a partir do endereço que a ferramenta publica — a menos que a conexão carregue um segredo endpoint, caso em que MCP_URL_<ALIAS> é esse segredo e o endereço publicado não é entregue de forma alguma. Uma conexão que carrega uma credential acrescenta MCP_CREDENTIAL_<ALIAS> e MCP_CREDENTIAL_HEADER_<ALIAS>, o cabeçalho da requisição que a ferramenta publica para apresentá-la.
- No Kubernetes o segredo é uma entrada de vinculação que nomeia a conexão e o slot —
connection: search,from: endpoint,as: env— que o provedor transforma nosecretKeyRefacima, lendo o nome e a chave de dados do Secret a partir do quehelm/k8s-existing-secretpublica. - No Docker Compose o segredo chega ao canal de injeção do agente sob a chave com que a sua própria vinculação o entregou,
values.key, e a Recipe escreve esse valor no ambiente do serviço.
Escrita em vez disso no infra.endpoint da ferramenta, a chave vai para onde quer que o endereço publicado vá: o MCP_URL_SEARCH do agente a carrega como valor literal, no Deployment no Kubernetes e no ambiente do serviço no arquivo do Compose, porque a realização de referência publica o endereço como está escrito.
Limites
-
No Docker Compose, dois segredos que só a Release vincula a um mesmo agente colidem. Cada vinculação
core/secret-valueque uma Release faz entrega sob a chave padrão da Feature,value, então uma segunda no mesmo agente — o endereço de outro servidor, ou uma credencial ao lado desta — interrompe o build. Uma Release que vincula tanto umendpointquanto umacredentialasearchimprime:[… 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.A chave é uma folha de
values, que só o Aggregate escreve, então um Aggregate que declara uma das duas vinculações e nomeia a suavalues.keyevita isso: a Recipe de compose do agente lê cada segredo sob a chave que a sua própria vinculação nomeia. O Kubernetes não tem esse limite, porque lá cada segredo é uma referência a um Secret por nome e chave de dados, e não um valor entregue sob uma chave. -
Uma chave no caminho do endereço. Quando o servidor lê a sua chave do caminho em vez da query string, o endereço da ferramenta é o endereço sem essa parte do caminho, e o Secret guarda o endereço inteiro.
-
O host é escrito duas vezes, às claras no endereço da ferramenta e dentro do Secret, e nada verifica se os dois coincidem, porque o compilador nunca lê um Secret.
Montar o endereço em tempo de execução apenas a partir da chave, com uma referência $(VAR) em uma variável simples, só funciona no Kubernetes: o Kubernetes expande uma referência assim a partir das entradas listadas antes dela no contêiner, e o provedor helm lista as entradas que lê de um Secret antes das variáveis simples, enquanto o Docker Compose não expande nenhuma referência $(VAR) entre as entradas de ambiente de um serviço.
Adaptando-o
- Um servidor que também verifica um cabeçalho. Vincule
credentialna mesma conexão. O agente recebeMCP_CREDENTIAL_SEARCHe o cabeçalho sob o qual apresentá-la,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, a menos que a Release nomeie o cabeçalho próprio do servidor eminfra.credential_headerda ferramenta. No Docker Compose, nomeie no Aggregate a chave de uma das duas, como acima. - Vários servidores. Ligue uma conexão por servidor no socket
tools. As variáveis de cada conexão levam o seu alias, e cada conexão guarda os seus próprios segredos. - Um servidor que lê a sua chave apenas de um cabeçalho. Deixe
endpointde fora, eMCP_URL_<ALIAS>é o endereço que a ferramenta publica.
Determinismo
As duas Releases fazem o build com --verify-determinism, que renderiza cada nó duas vezes e compara os bytes emitidos:
aggrega build --release release-helm.yaml --verify-determinismRefazer o build de qualquer uma das duas a partir de uma árvore limpa reproduz a sua saída renderizada byte a byte.
Arquivos
aggregate.yaml— a ferramenta e o agente, ligados por meio do sockettools, sem nenhum segredo vinculado.manifest-helm.yaml,manifest-compose.yaml— a ferramenta paramcp-remote, o agente para a sua própria Recipe, e a Feature de credencial que cada destino usa.release-helm.yaml,release-compose.yaml— o endereço da ferramenta sem a sua chave, a imagem do agente, e o segredoendpointna conexão do agente.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— o agente: o seu sockettoolscom os slotscredentialeendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— o agente em cada destino..aggrega-config.yaml— a pilha de busca do catálogo e o registro.build-release.sh— faz o build de uma Release, exibindo o comandoaggrega buildequivalente.
Para uma chave que o agente apresenta em um cabeçalho, guardada na conexão em que é apresentada, veja connection-credentials. O modelo por trás de ambos é o Modelo de credenciais, e as realizações da ferramenta são descritas com o rótulo de transporte de ferramenta em Features de IA.