Адреса інструмента із секрету Secret — сервер Model Context Protocol, що зчитує свій ключ зі своєї адреси
Деякі сервери Model Context Protocol, які запускає хтось інший, зчитують свій ключ
зі своєї власної адреси — https://mcp.example.com/mcp?api_key=<key> — а не
із заголовка запиту. Таку адресу не можна записати в інструмент так, як
звичайну: інструмент публікує свою адресу в тому вигляді, як її записано, тож ключ
потрапив би в кожен файл, куди потрапляє адреса.
Цей робочий простір зберігає адресу у двох частинах. Інструмент, core/ai-tool/mcp,
зберігає адресу без тієї частини, що містить ключ. З’єднання агента
з інструментом зберігає всю адресу як секрет, а сутність Release вказує, де він
міститься. Робочий простір збирається для Kubernetes і для Docker Compose, і в обох випадках жоден згенерований
файл не містить ключа.
Агента оголошено у власному каталозі цього робочого простору, тож сокет, що зберігає адресу, тут розписано повністю. Середовища виконання агентів зі стандартної бібліотеки core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk і mastra, а також платформи core/ai-agent/flowise і n8n, оголошують сокет tools з тими самими двома слотами. Інструмент, дві сутності Features облікових даних та їхні реалізації постачаються в каталозі стандартної бібліотеки.
Що він збирає
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
search | core/ai-tool/mcp | сервер Model Context Protocol, який запускає хтось інший, зіставлений із mcp-remote, що нічого не запускає |
agent | local/ai-agent/mcp-client | агент, під’єднаний до search через свій сокет tools |
Дві сутності Releases спільно використовують один Aggregate, і кожна має власний Manifest:
| Release | Manifest | ціль | звідки береться повна адреса |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | Secret, який уже є в просторі імен: core/referenced-secret, прив’язаний до helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | посилання на змінну Compose: core/secret-value, прив’язаний до compose/dotenv-secret |
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example mcp-address-from-secretПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd mcp-address-from-secretЗбирання
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/Кожна сутність Release записує до власного каталогу, тож два згенеровані дерева співіснують і їх можна порівняти поруч.
.aggrega-config.yaml перелічує власний catalog/ цього робочого простору, що містить агента та дві його сутності Recipes; усе інше розв’язується з hub.aggrega.ai — реєстру за замовчуванням, який він називає. Якщо робочу копію каталогу стандартної бібліотеки (де її взяти) вказано через --catalog, кожна сутність розв’язується з цих двох каталогів, тож збирання завершується й з --offline, що забороняє будь-які звернення до мережі. --auto-pull записує lock-файл кожної сутності Release під час збирання; lock-файли та згенерований вивід створюються автоматично й не постачаються.
Збирання для Kubernetes виводить таке, де <workspace> позначає теку цього прикладу:
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Збирання для compose виводить ті самі рядки для release-compose.yaml, причому його сповіщення називає core/secret-value, і записує один файл. Рядок notice: стосується облікової сутності Feature, яку приєднує сутність Release: вона приймає локатор секрету, origin, із values розробника або infra оператора, і це попередження повідомляє, що один лист оголошено в обох стовпах. Воно не змінює жодного вердикту й жодного згенерованого байта.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `mcp-address-from-secret`, викличте один раз інструмент `scaffold`, задавши для `example` значення `mcp-address-from-secret`, без `dir`: він запише приклад у нову теку `mcp-address-from-secret`. Потім викличте інструмент `build` один раз для кожного файлу Release у такому порядку — `release-helm.yaml` і `release-compose.yaml` — щоразу задаючи для `workspace_root` значення `mcp-address-from-secret`, для `release` — цей файл, для `auto_pull` — true і для `write` — true. Скажіть, які файли записала кожна збірка; вони розташовані в `mcp-address-from-secret/dist/`.Інструмент містить адресу без свого ключа
З release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote зчитує з цієї адреси хост, порт і схему, які публікує, і створює для інструмента один файл: Service типу ExternalName, що зіставляє внутрішньокластерне ім’я з хостом. Увесь spec файлу
dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Отже, адреса, яку містить інструмент, потребує щонайменше схеми й хоста і не містить нічого з тієї частини, що несе ключ. compose/mcp-remote взагалі не визначає сервісу для інструмента.
З’єднання агента містить повну адресу
Component агента оголошує два слоти секретів на своєму сокеті tools. З
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, без описів:
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 містить ключ, який агент подає в заголовку запиту; endpoint містить
повну адресу — для сервера, що читає свій ключ із самої адреси.
unauthenticated — це власне твердження з’єднання, що його інструмент не потребує
облікових даних, і воно нічого не змінює в тому, що рендерить агент. Усі три розміщено на
з’єднанні, тож агент, який звертається до кількох серверів, тримає секрет кожного сервера на
з’єднанні з цим сервером.
Release заповнює endpoint на з’єднанні, яке під’єднав Aggregate. З
release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressRelease не записує values, тож origin міститься в infra, а ключ даних, що читається
із Secret, — це типове значення Feature, value. Manifest прив’язує
core/referenced-secret до helm/k8s-existing-secret, який читає origin як
ім’я Secret, що вже є в просторі імен, і нічого не рендерить. Secret
створюється поза Release тим, хто його розгортає:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'Контейнер агента читає з нього адресу. env у
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 — це повна адреса, прочитана із Secret за іменем і ключем даних;
MCP_HOST_SEARCH — хост, який публікує інструмент. dist/kubernetes/helm/ містить
Deployment агента й Service інструмента і нічого більше: жоден Secret не
рендериться, і жоден файл не містить ключа.
У Docker Compose
Compose не має посилань на секрети, тому Release для compose заповнює той самий слот за допомогою
core/secret-value, джерелом якого є посилання на змінну Compose. З
release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret доставляє посилання як написано, і сервіс агента
його містить. environment сервісу agent у
dist/local/compose/docker-compose.yaml, який визначає цей сервіс і жодного
іншого:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose підставляє SEARCH_MCP_URL під час запуску стека — з
середовища оболонки, з файлу, указаного через --env-file, або з файлу .env у
каталозі проєкту, — тож файл містить лише посилання.
Як сутності Recipes агента читають слот
Кожне з’єднання на сокеті tools стає змінними середовища, названими за псевдонімом з’єднання великими літерами: MCP_HOST_<ALIAS> — з хоста, який публікує інструмент, і MCP_URL_<ALIAS> — з адреси, яку публікує інструмент, якщо тільки з’єднання не несе секрет endpoint: у такому разі MCP_URL_<ALIAS> — це той секрет, а опублікована адреса не доставляється взагалі. З’єднання, що несе credential, додає MCP_CREDENTIAL_<ALIAS> і MCP_CREDENTIAL_HEADER_<ALIAS> — заголовок запиту, який інструмент публікує для його передавання.
- У Kubernetes секрет — це запис вкладення, що називає з’єднання і
слот —
connection: search,from: endpoint,as: env, — який провайдер перетворює наsecretKeyRefвище, читаючи ім’я Secret і ключ даних з того, що публікуєhelm/k8s-existing-secret. - У Docker Compose секрет надходить у канал inject агента під
ключем, під яким його доставило власне вкладення,
values.key, і Recipe записує це значення в середовище сервісу.
Якщо ж записати ключ у infra.endpoint інструмента, він потрапляє туди ж, куди й
опублікована адреса: MCP_URL_SEARCH агента несе його як літеральне
значення — у Deployment у Kubernetes і в середовищі сервісу у файлі
Compose, — тому що еталонна реалізація публікує адресу так, як її
записано.
Обмеження
-
На Docker Compose два секрети, які сама сутність Release прикріплює до одного агента, конфліктують. Кожне прикріплення
core/secret-value, яке робить Release, доставляється під типовим ключем сутності Feature,value, тож друге прикріплення до того самого агента — адреса іншого сервера або облікові дані поряд із цією — зупиняє збирання. Release, що прикріплює доsearchіendpoint, іcredential, виводить:[… 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.Ключ є листком
values, який записує лише Aggregate, тож Aggregate, що оголошує одне з двох прикріплень і називає йогоvalues.key, уникає цього: compose-сутність Recipe агента читає кожен секрет під ключем, який називає його власне прикріплення. Kubernetes не має такого обмеження, бо кожен секрет там є посиланням на Secret за іменем і ключем даних, а не значенням, доставленим під ключем. -
Ключ у шляху адреси. Якщо сервер читає свій ключ зі шляху, а не з рядка запиту, адреса інструмента — це адреса без цієї частини шляху, а Secret містить її повністю.
-
Хост записано двічі: відкрито в адресі інструмента та всередині Secret, і ніщо не перевіряє, чи вони збігаються, бо компілятор ніколи не читає Secret.
Збирання адреси під час виконання лише з ключа, за допомогою посилання $(VAR)
у звичайній змінній, працює тільки на Kubernetes: Kubernetes розгортає
таке посилання із записів, перелічених перед ним у контейнері, а
провайдер helm перелічує записи, які читає із Secret, перед звичайними
змінними, тоді як Docker Compose не розгортає жодного посилання $(VAR) між
записами середовища сервісу.
Адаптація прикладу
- Сервер, який також перевіряє заголовок. Приєднайте
credentialдо того самого з’єднання. Агент отримуєMCP_CREDENTIAL_SEARCHі заголовок, під яким його слід передати,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, якщо тільки Release не називає власний заголовок сервера вinfra.credential_headerінструмента. На Docker Compose назвіть ключ одного з двох в Aggregate, як описано вище. - Кілька серверів. Під’єднайте по одному з’єднанню на кожен сервер до сокета
tools. Змінні кожного з’єднання містять його псевдонім, і кожне з’єднання має власні секрети. - Сервер, який читає свій ключ лише із заголовка. Не вказуйте
endpoint, іMCP_URL_<ALIAS>буде адресою, яку публікує інструмент.
Детермінованість
Обидві сутності Releases збираються з --verify-determinism, який рендерить кожен вузол двічі
і порівнює згенеровані байти:
aggrega build --release release-helm.yaml --verify-determinismПовторна збірка будь-якої з них із чистого дерева відтворює її відрендерений результат байт у байт.
Файли
aggregate.yaml— інструмент і агент, з’єднані через сокетtools, без прикріпленого секрету.manifest-helm.yaml,manifest-compose.yaml— інструмент доmcp-remote, агент до власного Recipe і облікова Feature, яку використовує кожна ціль.release-helm.yaml,release-compose.yaml— адреса інструмента без його ключа, образ агента і секретendpointна з’єднанні агента.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— агент: його сокетtoolsзі слотамиcredentialіendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— агент на кожній цілі..aggrega-config.yaml— стек пошуку каталогів і реєстр.build-release.sh— збирає одну сутність Release і виводить еквівалентну командуaggrega build.
Про ключ, який агент передає в заголовку і який зберігається на з’єднанні, де його передають, див. connection-credentials. Модель, що лежить в основі обох, — модель облікових даних, а реалізації інструмента описано з міткою транспорту інструмента в AI Features.