Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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ânciaComponent do catálogoo que é aqui
searchcore/ai-tool/mcpum servidor Model Context Protocol gerido por terceiros, mapeado para mcp-remote, que não executa nada
agentlocal/ai-agent/mcp-cliento agente, ligado a search através do seu socket tools

Duas Releases partilham o único Aggregate, cada uma com um Manifest próprio:

ReleaseManifestdestinode onde vem o endereço completo
release-helm.yamlmanifest-helm.yamlKubernetesum Secret que o namespace já contém: core/referenced-secret associado a helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeuma 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:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd mcp-address-from-secret

Compilação

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

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

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

Assim, 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-address

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

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

MCP_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 no secretKeyRef acima, lendo o nome e a chave de dados do Secret a partir do que helm/k8s-existing-secret publica.
  • 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-value que 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 um endpoint como uma 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.

    A chave é uma folha de values, que só o Aggregate escreve, pelo que um Aggregate que declara um dos dois anexos e nomeia a sua values.key o 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 credential na mesma ligação. O agente recebe MCP_CREDENTIAL_SEARCH e 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 em infra.credential_header da 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 endpoint de fora, e MCP_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:

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

Recompilar 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 socket tools, sem nenhum segredo anexado.
  • manifest-helm.yaml, manifest-compose.yaml — a ferramenta para mcp-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 segredo endpoint na ligação do agente.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — o agente: o seu socket tools com os slots credential e endpoint.
  • 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 comando aggrega build equivalente.

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.