Перейти к содержимому
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, где 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.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 раскрывает такую ссылку из записей, перечисленных перед ней в контейнере, а 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: этот флаг рендерит каждый узел дважды и сравнивает выданные байты:

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.