Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

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

instancjaencja Component z kataloguczym jest tutaj
searchcore/ai-tool/mcpserwer Model Context Protocol uruchamiany przez kogoś innego, zmapowany na mcp-remote, który niczego nie uruchamia
agentlocal/ai-agent/mcp-clientagent połączony z search przez swoje gniazdo tools

Dwie encje Releases współdzielą jedną encję Aggregate, każda z własną encją Manifest:

ReleaseManifestcelskąd pochodzi pełny adres
release-helm.yamlmanifest-helm.yamlKubernetesobiekt Secret, który już istnieje w przestrzeni nazw: core/referenced-secret powiązany z helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeodwoł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:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd mcp-address-from-secret

Kompilacja

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

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

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

Adres 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-address

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

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

MCP_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ższy secretKeyRef, odczytując nazwę obiektu Secret i klucz danych z tego, co publikuje helm/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-value wykonane 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 do search zarówno endpoint, jak i credential wypisuje:

    [… 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.

    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 jego values.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ć credential do tego samego połączenia. Agent otrzymuje MCP_CREDENTIAL_SEARCH oraz nagłówek, pod którym ma je przedstawić, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, chyba że encja Release wskaże własny nagłówek serwera w infra.credential_header narzę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, a MCP_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:

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

Ponowne 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 gniazdo tools, bez dołączonego sekretu.
  • manifest-helm.yaml, manifest-compose.yaml — narzędzie przypisane do mcp-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 sekret endpoint w połączeniu agenta.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — agent: jego gniazdo tools ze slotami credential i endpoint.
  • 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 polecenie aggrega 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.