Adres narzędzia z obiektu Secret — serwer Model Context Protocol, który odczytuje swój klucz z własnego adresu
Niektóre serwery Model Context Protocol uruchamiane przez kogoś innego odczytują swój klucz z
własnego adresu — https://mcp.example.com/mcp?api_key=<key> — a nie
z nagłówka żądania. Takiego adresu nie można wpisać do narzędzia tak,
jak wpisuje się zwykły adres: narzędzie publikuje swój adres w postaci, w jakiej został zapisany, więc klucz
trafiłby do każdego pliku, do którego trafia adres.
Ten obszar roboczy przechowuje adres w dwóch częściach. Narzędzie, core/ai-tool/mcp,
przechowuje adres bez części zawierającej klucz. Połączenie agenta
z narzędziem przechowuje cały adres jako sekret, a encja Release wskazuje, gdzie
on się znajduje. Obszar roboczy buduje się dla Kubernetes i dla Docker Compose i w obu przypadkach żaden wyrenderowany
plik nie zawiera klucza.
Agent jest zadeklarowany we własnym katalogu tego obszaru roboczego, więc gniazdo przechowujące adres jest tu rozpisane w całości. Środowiska uruchomieniowe agentów z biblioteki standardowej core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk i mastra oraz platformy core/ai-agent/flowise i n8n deklarują gniazdo tools z tymi samymi dwoma slotami. Narzędzie, dwie encje Features dotyczące poświadczeń i ich realizacje są dostarczane w katalogu biblioteki standardowej.
Co powstaje
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
search | core/ai-tool/mcp | serwer Model Context Protocol uruchamiany przez kogoś innego, zmapowany na mcp-remote, który niczego nie uruchamia |
agent | local/ai-agent/mcp-client | agent połączony z search przez swoje gniazdo tools |
Dwie encje Releases współdzielą jedną encję Aggregate, każda z własną encją Manifest:
| Release | Manifest | cel | skąd pochodzi pełny adres |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | obiekt Secret, który już istnieje w przestrzeni nazw: core/referenced-secret powiązany z helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | odwołanie do zmiennej Compose: core/secret-value powiązany z compose/dotenv-secret |
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example mcp-address-from-secretNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd mcp-address-from-secretKompilacja
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/Każda encja Release zapisuje wynik we własnym katalogu, więc oba wygenerowane drzewa współistnieją i można je porównać obok siebie.
.aggrega-config.yaml wymienia własny catalog/ tego obszaru roboczego, który zawiera agenta i jego dwie encje Recipes; wszystko inne jest rozwiązywane z hub.aggrega.ai, domyślnego rejestru wskazanego w tym pliku. Gdy kopia robocza katalogu biblioteki standardowej (skąd ją pobrać) jest wskazana za pomocą --catalog, każda encja jest rozwiązywana z tych dwóch katalogów, więc budowanie kończy się powodzeniem także z --offline, które odrzuca każde odwołanie do sieci. --auto-pull zapisuje plik blokady każdej encji Release podczas budowania; pliki blokady i wygenerowany wynik są generowane, a nie dostarczane.
Budowanie dla Kubernetes wypisuje (<workspace> oznacza folder tego
przykładu):
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>/distBudowanie dla Compose wypisuje te same wiersze dla release-compose.yaml, przy czym jego komunikat
wymienia core/secret-value, i zapisuje jeden plik. Wiersz notice: dotyczy
encji Feature z poświadczeniem, którą dołącza encja Release: przyjmuje ona lokalizator sekretu,
origin, z values dewelopera lub z infra operatora, a
komunikat informacyjny zgłasza, że jeden liść jest zadeklarowany w obu filarach. Nie zmienia on żadnego werdyktu
ani żadnego wygenerowanego bajtu.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `mcp-address-from-secret`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `mcp-address-from-secret` i bez `dir`: zapisuje ono przykład w nowym folderze `mcp-address-from-secret`. Następnie wywołaj narzędzie `build` raz dla każdego pliku Release, w tej kolejności — `release-helm.yaml` i `release-compose.yaml` — za każdym razem z `workspace_root` ustawionym na `mcp-address-from-secret`, `release` ustawionym na ten plik, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj, które pliki zapisała każda kompilacja; znajdują się w `mcp-address-from-secret/dist/`.Narzędzie przechowuje adres bez klucza
Z pliku release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote odczytuje z tego adresu host, port i schemat, który publikuje,
i emituje jeden plik dla narzędzia: obiekt Service typu ExternalName, mapujący
nazwę wewnątrz klastra na ten host. Cała sekcja spec pliku
dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Adres przechowywany przez narzędzie musi więc zawierać co najmniej schemat i host
i nie zawiera niczego z części niosącej klucz. compose/mcp-remote nie definiuje
żadnej usługi dla narzędzia.
Połączenie agenta przechowuje cały adres
Encja Component agenta deklaruje dwa sloty sekretów w swoim gnieździe tools. Z pliku
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, z pominięciem
opisów:
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 przechowuje klucz, który agent przedstawia w nagłówku żądania; endpoint przechowuje
cały adres, dla serwera, który odczytuje swój klucz z samego adresu.
unauthenticated to własna deklaracja połączenia, że jego narzędzie nie przyjmuje żadnych
poświadczeń, i nie zmienia niczego, co renderuje agent. Wszystkie trzy znajdują się w
połączeniu, więc agent łączący się z kilkoma serwerami przechowuje sekret każdego serwera w
połączeniu z tym serwerem.
Encja Release wypełnia endpoint w połączeniu, które utworzyła encja Aggregate. Z pliku
release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressEncja Release nie zapisuje values, więc origin znajduje się w infra, a kluczem danych odczytywanym
z obiektu Secret jest wartość domyślna encji Feature, value. Encja Manifest wiąże
core/referenced-secret z helm/k8s-existing-secret, który odczytuje origin jako
nazwę obiektu Secret istniejącego już w przestrzeni nazw i niczego nie renderuje. Obiekt Secret
jest tworzony poza encją Release, przez tego, kto ją wdraża:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'Kontener agenta odczytuje z niego adres. Sekcja env pliku
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 to cały adres, odczytywany z obiektu Secret według nazwy i klucza danych;
MCP_HOST_SEARCH to host publikowany przez narzędzie. dist/kubernetes/helm/ zawiera
Deployment agenta i Service narzędzia i nic więcej: żaden obiekt Secret nie jest
renderowany i żaden plik nie zawiera klucza.
W Docker Compose
Compose nie ma odwołań do sekretów, więc encja Release dla Compose wypełnia ten sam slot przy użyciu
core/secret-value, którego źródłem jest odwołanie do zmiennej Compose. Z pliku
release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret dostarcza odwołanie w zapisanej postaci, a usługa agenta
je przenosi. Sekcja environment usługi agent w pliku
dist/local/compose/docker-compose.yaml, który definiuje tę usługę i żadnej
innej:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose podstawia SEARCH_MCP_URL przy uruchamianiu stosu — ze
zmiennych środowiskowych powłoki, z pliku wskazanego przez --env-file lub z pliku .env w
katalogu projektu — więc plik zawiera wyłącznie odwołanie.
Jak encje Recipes agenta odczytują slot
Każde połączenie w gnieździe tools staje się zmiennymi środowiskowymi nazwanymi od aliasu połączenia zapisanego wielkimi literami: MCP_HOST_<ALIAS> z hosta publikowanego przez narzędzie oraz MCP_URL_<ALIAS> z adresu publikowanego przez narzędzie — chyba że połączenie zawiera sekret endpoint; wtedy MCP_URL_<ALIAS> jest tym sekretem, a opublikowany adres w ogóle nie jest dostarczany. Połączenie zawierające credential dodaje MCP_CREDENTIAL_<ALIAS> oraz MCP_CREDENTIAL_HEADER_<ALIAS>, czyli nagłówek żądania, który narzędzie publikuje jako ten, w którym należy go przedstawić.
- Na Kubernetes sekret jest wpisem załącznika wskazującym połączenie i
slot —
connection: search,from: endpoint,as: env— który dostawca zamienia na powyższysecretKeyRef, odczytując nazwę obiektu Secret i klucz danych z tego, co publikujehelm/k8s-existing-secret. - Na Docker Compose sekret trafia do potoku inject agenta pod
kluczem, pod którym dostarczył go jego własny załącznik,
values.key, a encja Recipe zapisuje tę wartość w środowisku usługi.
Jeśli zamiast tego klucz zostanie zapisany w infra.endpoint narzędzia, trafia wszędzie tam, gdzie
opublikowany adres: MCP_URL_SEARCH agenta zawiera go jako wartość
dosłowną, w obiekcie Deployment na Kubernetes i w środowisku usługi w
pliku Compose, ponieważ realizacja referencyjna publikuje adres w postaci,
w jakiej go zapisano.
Ograniczenia
-
W Docker Compose dwa sekrety, które sama encja Release dołącza do jednego agenta, kolidują ze sobą. Każde dołączenie
core/secret-valuewykonane przez encję Release dostarcza wartość pod domyślnym kluczem encji Feature,value, więc drugie takie dołączenie na tym samym agencie — adres innego serwera albo poświadczenie obok tego — zatrzymuje kompilację. Encja Release dołączająca dosearchzarównoendpoint, jak icredentialwypisuje:[… 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.Klucz jest liściem
values, który zapisuje wyłącznie encja Aggregate, więc encja Aggregate, która deklaruje jedno z dwóch dołączeń i nazywa jegovalues.key, unika tego problemu: Recipe compose agenta odczytuje każdy sekret pod kluczem, który nazywa jego własne dołączenie. Kubernetes nie ma takiego ograniczenia, ponieważ każdy sekret jest tam odwołaniem do obiektu Secret przez nazwę i klucz danych, a nie wartością dostarczaną pod kluczem. -
Klucz w ścieżce adresu. Jeśli serwer odczytuje klucz ze ścieżki, a nie z ciągu zapytania, adresem narzędzia jest adres z usuniętą tą częścią ścieżki, a Secret przechowuje go w całości.
-
Host jest zapisany dwukrotnie: jawnie w adresie narzędzia i wewnątrz obiektu Secret, a nic nie sprawdza, czy oba się zgadzają, ponieważ kompilator nigdy nie odczytuje obiektu Secret.
Składanie adresu w czasie działania z samego klucza, za pomocą odwołania $(VAR)
w zwykłej zmiennej, działa tylko w Kubernetes: Kubernetes rozwija
takie odwołanie na podstawie wpisów wymienionych przed nim w kontenerze, a
provider helm wymienia wpisy odczytywane z obiektu Secret przed zwykłymi
zmiennymi, natomiast Docker Compose nie rozwija żadnego odwołania $(VAR) między wpisami
środowiska usługi.
Dostosowywanie przykładu
- Serwer, który sprawdza także nagłówek. Należy dołączyć
credentialdo tego samego połączenia. Agent otrzymujeMCP_CREDENTIAL_SEARCHoraz nagłówek, pod którym ma je przedstawić,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, chyba że encja Release wskaże własny nagłówek serwera winfra.credential_headernarzędzia. W Docker Compose należy nazwać klucz jednego z nich w encji Aggregate, jak wyżej. - Kilka serwerów. Należy podłączyć jedno połączenie na serwer w gnieździe
tools. Zmienne każdego połączenia zawierają jego alias, a każde połączenie przechowuje własne sekrety. - Serwer, który odczytuje klucz wyłącznie z nagłówka. Należy pominąć
endpoint, aMCP_URL_<ALIAS>jest adresem publikowanym przez narzędzie.
Determinizm
Obie encje Releases budują się z flagą --verify-determinism, która renderuje każdy węzeł dwukrotnie i porównuje wyemitowane bajty:
aggrega build --release release-helm.yaml --verify-determinismPonowne zbudowanie dowolnej z nich z czystego drzewa odtwarza jej wyrenderowane wyjście bajt po bajcie.
Pliki
aggregate.yaml— narzędzie i agent, połączone przez gniazdotools, bez dołączonego sekretu.manifest-helm.yaml,manifest-compose.yaml— narzędzie przypisane domcp-remote, agent do własnej encji Recipe oraz encja Feature poświadczeń, której używa każdy cel.release-helm.yaml,release-compose.yaml— adres narzędzia bez jego klucza, obraz agenta oraz sekretendpointw połączeniu agenta.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— agent: jego gniazdotoolsze slotamicredentialiendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— agent na każdym z celów..aggrega-config.yaml— stos wyszukiwania katalogów i rejestr.build-release.sh— buduje jedną encję Release, wypisując równoważne polecenieaggrega build.
Klucz, który agent przedstawia w nagłówku i który jest przechowywany w połączeniu, na którym jest przedstawiany, opisuje przykład connection-credentials. Model, na którym opierają się oba przykłady, to Credential Model, a realizacje narzędzia opisano wraz z etykietą transportu narzędzia w rozdziale AI Features.