O endereço de uma ferramenta a partir de um Secret — um servidor Model Context Protocol que lê a sua chave a partir do seu endereço
Alguns servidores Model Context Protocol geridos por terceiros leem a sua chave a partir do próprio endereço — https://mcp.example.com/mcp?api_key=<key> — em vez de um cabeçalho do pedido. Um endereço assim não pode ser escrito na ferramenta como um endereço comum: a ferramenta publica o seu endereço tal como está escrito, pelo que a chave chegaria a todos os ficheiros 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 contém a chave. A ligação do agente à ferramenta guarda o endereço completo como segredo, e a Release nomeia onde este se encontra. Compila para Kubernetes e para Docker Compose, e em ambos nenhum ficheiro renderizado contém a chave.
O agente é declarado no catálogo próprio deste espaço de trabalho, pelo que o socket que guarda o endereço é escrito aqui na íntegra. Os runtimes de agentes da biblioteca standard 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 são fornecidas no catálogo da biblioteca standard.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
search | core/ai-tool/mcp | um servidor Model Context Protocol gerido por terceiros, mapeado para mcp-remote, que não executa nada |
agent | local/ai-agent/mcp-client | o agente, ligado a search através do seu socket tools |
Duas Releases partilham o único Aggregate, cada uma com um Manifest próprio:
| Release | Manifest | destino | de onde vem o endereço completo |
|---|---|---|---|
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
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example mcp-address-from-secretDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd mcp-address-from-secretCompilação
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, pelo que 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 registo predefinido que indica. Com uma cópia local do catálogo da biblioteca standard (onde obter uma) indicada com --catalog, cada entidade é resolvida a partir desses dois diretórios, pelo que a compilação também termina com --offline, que recusa qualquer acesso à rede. --auto-pull escreve o ficheiro de bloqueio de cada Release durante a compilação; os ficheiros de bloqueio e a saída renderizada são gerados, não distribuídos.
A compilação 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>/distA compilação para compose imprime as mesmas linhas para release-compose.yaml, com o seu aviso a nomear core/secret-value, e escreve um ficheiro. A linha notice: diz respeito à Feature de credencial que a Release anexa: aceita o localizador do segredo, origin, dos values do programador ou da infra do operador, e o aviso comunica que uma folha está declarada em ambos os pilares. Não altera nenhum veredicto nem nenhum byte renderizado.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta da área de trabalho ainda não contiver uma pasta `mcp-address-from-secret`, chame uma vez a ferramenta `scaffold` com `example` definido como `mcp-address-from-secret` e sem `dir`: esta escreve o exemplo numa nova pasta `mcp-address-from-secret`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-helm.yaml` e `release-compose.yaml` —, de cada vez com `workspace_root` definido como `mcp-address-from-secret`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique quais os ficheiros que cada compilação escreveu; encontram-se 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 ficheiro para a ferramenta: um Service ExternalName que mapeia um nome interno ao cluster para o host. O spec completo de dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Assim, o endereço que a ferramenta guarda precisa de pelo menos um esquema e um host, e não guarda nada da parte que contém a chave. compose/mcp-remote não define nenhum serviço para a ferramenta.
A ligação do agente guarda o endereço completo
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 num cabeçalho do pedido; endpoint guarda o endereço completo, para um servidor que lê a sua chave a partir do próprio endereço. unauthenticated é a declaração da própria ligação de que a sua ferramenta não exige credencial, e não altera nada do que o agente renderiza. Os três ficam na ligação, pelo que um agente que chega a vários servidores guarda o segredo de cada servidor na ligação desse servidor.
A Release preenche endpoint na ligação que o Aggregate estabeleceu. De release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressUma Release não escreve values, pelo que origin fica em infra, e a chave de dados lida do Secret é a predefinida 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 implementa:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'O contentor do agente lê o endereço a partir 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 completo, 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 ficheiro contém a chave.
No Docker Compose
O Compose não tem referência a segredos, pelo que 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 tal como está escrita, e o serviço do agente contém-na. 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 arranca — a partir do ambiente da shell, de um ficheiro indicado com --env-file ou do ficheiro .env no diretório do projeto — pelo que o ficheiro contém apenas a referência.
Como as Recipes do agente leem o slot
Cada ligação no socket tools torna-se variáveis de ambiente com o nome do alias da ligaçã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 ligação tenha um segredo endpoint, caso em que MCP_URL_<ALIAS> é esse segredo e o endereço publicado não é de todo entregue. Uma ligação com uma credential acrescenta MCP_CREDENTIAL_<ALIAS> e MCP_CREDENTIAL_HEADER_<ALIAS>, o cabeçalho do pedido que a ferramenta publica para a apresentar.
- No Kubernetes o segredo é uma entrada de anexo que nomeia a ligação e o slot —
connection: search,from: endpoint,as: env— que o fornecedor 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 o seu próprio anexo o entregou,
values.key, e a Recipe escreve esse valor no ambiente do serviço.
Escrita antes no infra.endpoint da ferramenta, a chave vai para onde quer que o endereço publicado vá: o MCP_URL_SEARCH do agente contém-na como valor literal, no Deployment no Kubernetes e no ambiente do serviço no ficheiro do Compose, porque a realização de referência publica o endereço tal como está escrito.
Limites
-
No Docker Compose, dois segredos que só a Release anexa a um mesmo agente colidem. Cada anexo
core/secret-valueque uma Release faz entrega sob a chave predefinida da Feature,value, pelo que um segundo no mesmo agente — o endereço de outro servidor, ou uma credencial ao lado desta — interrompe a compilação. Uma Release que anexa tanto umendpointcomo 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, pelo que um Aggregate que declara um dos dois anexos e nomeia a suavalues.keyo evita: a Recipe de compose do agente lê cada segredo sob a chave que o seu próprio anexo nomeia. O Kubernetes não tem esse limite, porque aí 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 a partir 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 completo.
-
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) numa variável simples, só funciona no Kubernetes: o Kubernetes expande uma referência deste tipo a partir das entradas listadas antes dela no contentor, e o fornecedor 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.
Adaptá-lo
- Um servidor que também verifica um cabeçalho. Anexar
credentialna mesma ligação. O agente recebeMCP_CREDENTIAL_SEARCHe o cabeçalho sob o qual a apresentar,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, nomear no Aggregate a chave de uma das duas, como acima. - Vários servidores. Estabelecer uma ligação por servidor no socket
tools. As variáveis de cada ligação levam o seu alias, e cada ligação guarda os seus próprios segredos. - Um servidor que lê a sua chave apenas a partir de um cabeçalho. Deixar
endpointde fora, eMCP_URL_<ALIAS>é o endereço que a ferramenta publica.
Determinismo
As duas Releases compilam com --verify-determinism, que renderiza cada nó duas vezes e compara os bytes emitidos:
aggrega build --release release-helm.yaml --verify-determinismRecompilar qualquer uma das duas a partir de uma árvore limpa reproduz a sua saída renderizada byte a byte.
Ficheiros
aggregate.yaml— a ferramenta e o agente, ligados através do sockettools, sem nenhum segredo anexado.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 ligaçã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 pesquisa do catálogo e o registo.build-release.sh— compila uma Release, mostrando o comandoaggrega buildequivalente.
Para uma chave que o agente apresenta num cabeçalho, guardada na ligação em que é apresentada, veja-se connection-credentials. O modelo por detrás de ambos é o Modelo de credenciais, e as realizações da ferramenta são descritas com a etiqueta de transporte de ferramenta em Features de IA.