Імпорт конфігурації клієнта MCP
Цей покроковий посібник імпортує сервери Model Context Protocol, з якими налаштовано помічника з програмування, — два, які він запускає з командного рядка, і один, який запускає хтось інший, — і збирає сервери для Kubernetes, щоб агент, що працює в кластері, мав доступ до тих самих інструментів. Імпорт створює чернетку кожного файлу, який читає збірка: командний рядок або адресу кожного сервера, реалізацію, яка його запускає, і те, звідки надходить токен сервера GitHub. Кожен файл і кожен блок виводу нижче взято з реального запуску; конфігурація та кожен етап посібника містяться в прикладі import-mcp, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, те, що він виводить, і блоки, які цитує ця сторінка, зі збереженими там файлами, а також валідує та збирає те, що записав імпорт.
Створення прикладу
Цей імпорт можна виконати командами з цієї сторінки або доручити його вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example import-mcpПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:
cd import-mcp
Конфігурація
.mcp.json Claude Code у корені проєкту:
{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "docs-search": { "type": "http", "url": "https://mcp.example.com/docs/mcp", "headers": { "Authorization": "Bearer ${DOCS_API_KEY}" } } }}Так само імпорт читає claude_desktop_config.json Claude Desktop, .cursor/mcp.json Cursor, .vscode/mcp.json Visual Studio Code і server.json реєстру MCP. Поруч із конфігурацією .aggrega-config.yaml робить теку робочим простором:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside .mcp.json.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.ai--target створює чернетку сутності Manifest із сутностей Recipes каталогу. Робочий простір не вказує жодної теки каталогу, тому імпорт читає каталог стандартної бібліотеки з реєстру, з якого отримує свій імпортер: підписаний знімок опублікованого каталогу, який перший імпорт отримує, перевіряє та зберігає в кеші вмісту робочого простору і який запис, що його імпорт пише поруч зі своїми чернетками, називає за дайджестом. Робочий простір, що вказує власні теки каталогу — у AGGREGA_CATALOG_DIRS або в workspace.catalog_dirs, — натомість імпортує на їх основі.
Файл відповідей
У Kubernetes сервер GitHub читає свій токен із Secret, який зберігає кластер, і жодна конфігурація MCP не називає цей Secret: конфігурація читає токен зі змінної GITHUB_TOKEN вашої оболонки. Тому імпорт запитує ім’я Secret. Приклад зберігає відповідь у import-answers.yaml, поруч із .mcp.json, де імпорт її шукає:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.github.features.server_env.infra.origin: "github-mcp-token"Імпорт сам записав цей файл, коли його вперше запустили без відповіді: не маючи термінала, у якому можна було б запитати, він створив чернетку всього іншого, залишив ім’я Secret порожнім, перелічив ключ у файлі й зупинився з повідомленням
1 value the drafts leave empty is still owed, listed in the answers file <workspace>/import-answers.yaml: write it beside its key there, then run the import againУ терміналі він натомість ставить запитання і записує відповідь у файл для наступного імпорту. Відповідь — це ім’я Secret, github-mcp-token, а ніколи не сам токен. Файл відповідей імпорту повністю описує файл і запитання.
aggrega import перелічує кожен прапорець, який приймає команда, зокрема --answers, що вказує файл відповідей, збережений деінде.
Перейдіть у source:
cd sourceЗапуск імпорту
aggrega import .mcp.json --target helmУ стандартний вивід він виводить перелік записаного:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonУ стандартний потік помилок, де <workspace> позначає теку, у якій ви його запустили:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the mcp format, with drafted paths relative to <workspace>warn: the value of infra.stdio_command.0 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.1 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.2 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.0 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.1 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of headers.Authorization of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.endpoint of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptyPull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)
Кожен сервер є екземпляром інструмента MCP зі стандартної бібліотеки, core/ai-tool/mcp, тож імпорт не зважує жодного кандидата й не виводить жодного рядка mapped.
- Рядки
warnназивають значення, які містить конфігурація сервера. Жоден клієнт MCP не позначає жодне з них як облікові дані, а будь-яке з них може їх містити — ключ в аргументі командного рядка, токен в адресі, — тож імпорт називає кожен елемент командного рядка, кожен заголовок і кожну адресу, які він переніс, за сервером і місцем, і ніколи за значенням. Прочитайте їх, перш ніж ділитися чернеткою. Значенняenv${GITHUB_TOKEN}— це лише посилання на змінну, тож воно не містить власного значення, і жодне попередження його не називає. - Рядок
Pull completeозначає, що імпорт отримує те, від чого залежить чернетка сутності Release, як це робитьaggrega pull, уrelease.lock, щоб чернетки одразу проходили валідацію та збірку. З--offlineімпорт нічого не завантажує і називає командуaggrega pull, яку слід виконати.
Що він записує
Сутності Aggregate, Release і Manifest отримують назву imported/mcp за файлом, .mcp.json, оскільки конфігурація клієнта не має власної назви — server.json реєстру отримує назву за своїм name — у просторі імен, який задає налаштування target_namespace імпортера, тобто imported, якщо ви не задасте інший (Налаштування).
aggregate.yaml — по одному екземпляру на сервер і поки що нічого, що їх використовує:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/mcp version: 0.1.0 description: Draft Aggregate imported from a source in the mcp format.spec: components: github: type: core/ai-tool/mcp fetch: type: core/ai-tool/mcp docs-search: type: core/ai-tool/mcprelease.yaml — як запускається кожен сервер або як до нього звертатися, згідно з конфігурацією, а також Secret, з якого читається токен сервера GitHub:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/mcp # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the mcp format.spec: aggregate: imported/mcp manifest: imported/mcp components: github: infra: stdio_command: - "npx" - "-y" - "@modelcontextprotocol/server-github" stdio_runtime: npm features: server_env: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN. origin: "github-mcp-token" fetch: infra: stdio_command: - "uvx" - "mcp-server-fetch" stdio_runtime: pypi # The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool: # - Authorization: "Bearer ${DOCS_API_KEY}" docs-search: infra: endpoint: "https://mcp.example.com/docs/mcp"- Середовище,
development, — це типове значення, яке записує імпорт, оскільки жодна конфігурація його не вказує; змініть його, якщо сутність Release розгортається деінде. stdio_runtimeзчитується з кожної команди:npxзапускає пакет npm,uvx— пакет PyPI.- Токен GitHub. Середовище сервера стає його слотом
server_env. У Kubernetes реалізаціяcore/referenced-secret-set,helm/k8s-secret-set, записує передані їй значення в Secret, який рендерить збірка, і так токен потрапив би у файл. Тому для--target helmімпорт натомість приєднуєcore/referenced-secret, указуючи Secret, який уже є в кластері, — відповідь,github-mcp-token, — з одним ключем даних на змінну,GITHUB_PERSONAL_ACCESS_TOKEN. Міст імпортує кожен ключ даних цього Secret як змінну з тим самим іменем, тож сервер читає свій токен так само, як на вашій машині, і жоден відрендерений файл його не містить. - Заголовок
Authorizationзалишається коментарем. Облікові дані віддаленого сервера тримає той, хто його викликає, на власному з’єднанні цього викликача з інструментом, а в цьому робочому просторі викликача ще немає. Коли ви під’єднаєте агента доdocs-search, заголовок розміщується на тому з’єднанні.
manifest.yaml — одна реалізація на сервер, за його іменем, і реалізація Secret:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/mcp version: 0.1.0spec: mappings: components: type: {} name: github: helm/mcp-stdio-bridge fetch: helm/mcp-stdio-bridge docs-search: helm/mcp-remote features: type: core/referenced-secret: helm/k8s-existing-secretТри сутності Recipes для Kubernetes реалізують core/ai-tool/mcp — одна для сервера, опублікованого як образ, одна для пакета, що працює за мостом, одна для сервера, який запускає хтось інший, — і те, яка з них підходить, є властивістю кожного сервера, яку вказує конфігурація. Тому імпорт зіставляє кожен екземпляр за його іменем: github і fetch, що запускаються з командного рядка, працюють за мостом stdio, helm/mcp-stdio-bridge; docs-search, який запускає хтось інший, зіставляється з helm/mcp-remote, який нічого не запускає і публікує адресу. Secret токена зіставляється з helm/k8s-existing-secret, який посилається на Secret, а не записує його.
release.lock фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.
У Docker Compose
Сервери працюють і в Docker Compose. aggrega import .mcp.json --target compose зіставляє github і fetch з compose/mcp-stdio-bridge, а docs-search — з compose/mcp-remote, і зберігає середовище сервера GitHub так, як його записує конфігурація: запис core/referenced-secret-set, значенням якого є посилання на змінну ${GITHUB_TOKEN}, реалізований через compose/dotenv-secret-set, який записує його в середовище сервісу як є, тож Docker Compose заповнює його з вашої оболонки під час запуску стеку. Цей імпорт нічого не запитує і зберігає ім’я Secret у файлі відповідей, не використовуючи його.
Перевірка та збирання
aggrega validate --release release.yamlaggrega build --release release.yaml

Перевірка виводить:
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)і збірка, де <workspace> позначає теку, у якій ви її запустили:
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: 5 files written to <workspace>/distРядок notice має рекомендаційний характер: Feature приймає свій origin із values сутності Aggregate або з infra сутності Release, і повідомлення сповіщає, що один листовий вузол оголошено в обох місцях. Він не змінює жодного вердикту.
Збірка записує в dist/helm/ Deployment і Service для кожного з двох серверів за мостом і один Service для docs-search. Контейнер сервера GitHub у dist/helm/github-deployment.yaml запускає міст із командним рядком сервера й бере своє середовище із Secret:
containers: - name: main image: ghcr.io/supercorp-ai/supergateway:4.1.0@sha256:1938c43538a5308bce07d58028e9de00b7acfecb40b39b059b2f3931800ad910 args: - --stdio - '''npx'' ''-y'' ''@modelcontextprotocol/server-github''' - --outputTransport - streamableHttp - --stateful - --port - "8080" - --streamableHttpPath - /mcp - --healthEndpoint - /healthz ports: - name: http containerPort: 8080 env: - name: MCP_TOOL_SIDE_EFFECTS value: mutating - name: MCP_TOOL_TIMEOUT_SECONDS value: "30" - name: MCP_TOOL_PORT value: "8080" envFrom: - secretRef: name: github-mcp-token [… omitted: the container's resources and its readiness probe]dist/helm/docs-search-service.yaml нічого не запускає: він дає серверу, який запускає хтось інший, ім’я всередині кластера.
apiVersion: v1kind: Servicemetadata: name: docs-search [… omitted: the labels and annotations the build writes on every resource]spec: type: ExternalName externalName: mcp.example.com ports: - port: 443З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте в нього цей промпт.
Використовуй лише інструменти Aggrega і не створюй жодної теки самостійно. Якщо тека Workspace ще не містить теки `import-mcp`, виклич один раз інструмент `scaffold` з `example`, встановленим у `import-mcp`, і без `dir`: він записує приклад у нову теку `import-mcp`, тека `source` якої містить те, що імпортує ця сторінка. Потім виклич інструмент `import` з `workspace_root`, встановленим у `import-mcp/source`, `source`, встановленим у `.mcp.json`, і `target`, встановленим у `helm`: він читає потрібні відповіді з `import-answers.yaml` поруч із `.mcp.json`, записує свої чернетки в `import-mcp/source` і завантажує те, що їм потрібно. Потім виклич інструмент `validate` з `workspace_root`, встановленим у `import-mcp/source`, і `release`, встановленим у `release.yaml`, а також інструмент `build` з `workspace_root`, встановленим у `import-mcp/source`, `release`, встановленим у `release.yaml`, і `write`, встановленим у true. Скажи мені, які файли записала збірка; вони лежать у `import-mcp/source/dist/`.Відкриття у VS Code
Коли розширення Aggrega для Visual Studio Code встановлено, відкрийте у VS Code теку import-mcp/source, куди імпорт записав свої чернетки. Тека містить одну сутність Release, чернетку release.yaml, тож редактор вибирає її за вас і під час редагування перевіряє чернетки щодо цієї сутності Release, позначаючи знайдене у файлі та на панелі «Проблеми». Aggrega: Show topology graph у палітрі команд малює компоненти сутності Release і з’єднання між ними. Aggrega: Build, Aggrega: Preview build і Aggrega: Pull діють на ту саму сутність Release, і кожна з них також є кнопкою на панелі Commands подання Aggrega на панелі дій; Build записує свої файли в dist/ цієї теки. Решту описує Використання Aggrega у Visual Studio Code.
Запуск
Ніщо в результаті збирання не записує Secret github-mcp-token, тож створіть його, перш ніж застосовувати файли. Запишіть свій токен у github-token.env як один рядок GITHUB_PERSONAL_ACCESS_TOKEN=<your token> і створіть із нього Secret. Після цього токен зберігає кластер, тож видаліть файл:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdЗастосуйте результат збирання, як пояснює крок запуску в розділі Як виконується імпорт, і дочекайтеся обох серверів:
kubectl apply -R -f dist/helm/kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5mservice/docs-search createdservice/fetch-default createddeployment.apps/fetch createdservice/github-default createddeployment.apps/github createddeployment.apps/fetch condition metdeployment.apps/github condition metУ Docker Compose, у робочому просторі, імпортованому з --target compose і зібраному, запустіть стек із вашим токеном у змінній GITHUB_TOKEN вашої оболонки, яку Docker Compose читає під час запуску стеку:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitТестування
Міст надає кожен сервер через транспорт Streamable HTTP протоколу MCP, за адресою /mcp на порту 8080. Попросіть сервер fetch відкрити сеанс запитом MCP initialize, який не читає жодного токена.
У Docker Compose надішліть його з одноразового контейнера в мережі стеку, mcp_compose, де сервер має назву fetch:
docker run --rm --network mcp_compose curlimages/curl:8.11.1 -sS http://fetch:8080/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}': keepalive
[… omitted: the same comment, repeated while the server starts]
event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}У Kubernetes переадресуйте локальний порт на Service сервера, fetch-default, і залиште команду запущеною:
kubectl port-forward svc/fetch-default 8080:8080З іншого термінала надішліть той самий запит на перенаправлений порт:
curl -sS http://127.0.0.1:8080/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}': keepalive
: keepalive
event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}Відповідь називає сервер, mcp-fetch. Це займає певний час: міст запускає для кожного сеансу командний рядок сервера, uvx mcp-server-fetch, а uvx спершу завантажує та встановлює пакети сервера — під час запуску це тривало близько пів хвилини в Kubernetes і близько хвилини в Docker Compose. Рядки : keepalive — це коментарі, які потік тим часом надсилає.
Сервер GitHub відповідає на той самий запит за адресою http://github:8080/mcp у Docker Compose і через kubectl port-forward svc/github-default 8080:8080 у Kubernetes. initialize не читає жодного токена, тож відповідає незалежно від того, що містить токен; запуск використовував токен-заповнювач:
[… omitted: the keepalive comments, sent while npx installs the server]event: messagedata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-mcp-server","version":"0.6.2"}},"jsonrpc":"2.0","id":1}Зупиніть переадресацію порту, а потім видаліть те, що ви застосували, і Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenУ Docker Compose зупиніть і видаліть стек:
docker compose -p mcp -f dist/compose/docker-compose.yaml down