Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Адреса інструмента із секрету 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 із каталогущо це тут
searchcore/ai-tool/mcpсервер Model Context Protocol, який запускає хтось інший, зіставлений із mcp-remote, що нічого не запускає
agentlocal/ai-agent/mcp-clientагент, під’єднаний до search через свій сокет tools

Дві сутності Releases спільно використовують один Aggregate, і кожна має власний Manifest:

ReleaseManifestцільзвідки береться повна адреса
release-helm.yamlmanifest-helm.yamlKubernetesSecret, який уже є в просторі імен: core/referenced-secret, прив’язаний до helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composeпосилання на змінну Compose: core/secret-value, прив’язаний до compose/dotenv-secret

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd mcp-address-from-secret

Збирання

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

helm/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-address

Release не записує values, тож origin міститься в infra, а ключ даних, що читається із Secret, — це типове значення Feature, value. Manifest прив’язує core/referenced-secret до helm/k8s-existing-secret, який читає origin як ім’я Secret, що вже є в просторі імен, і нічого не рендерить. Secret створюється поза Release тим, хто його розгортає:

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

MCP_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.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.

    Ключ є листком 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, який рендерить кожен вузол двічі і порівнює згенеровані байти:

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