Адрес инструмента из 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-addressСущность Release не записывает 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, где origin — ссылка на переменную 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 раскрывает
такую ссылку из записей, перечисленных перед ней в контейнере, а
provider 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.