Importowanie konfiguracji klienta MCP
Ten przewodnik krok po kroku importuje serwery Model Context Protocol, z którymi skonfigurowany jest asystent programowania — dwa, które uruchamia z wiersza poleceń, i jeden, który prowadzi ktoś inny — i buduje serwery dla Kubernetes, tak aby agent działający w klastrze mógł sięgać do tych samych narzędzi. Import tworzy szkic każdego pliku, który odczytuje build: wiersz poleceń lub adres każdego serwera, realizację, która go uruchamia, oraz to, skąd pochodzi token serwera GitHub. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; konfiguracja i każdy etap przewodnika znajdują się w przykładzie import-mcp, gdzie skrypt sprawdzający ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.
Generowanie przykładu
Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example import-mcpNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:
cd import-mcp
Konfiguracja
Plik .mcp.json narzędzia Claude Code w głównym folderze projektu:
{ "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}" } } }}Import odczytuje w ten sam sposób claude_desktop_config.json z Claude Desktop, .cursor/mcp.json z Cursor, .vscode/mcp.json z Visual Studio Code oraz server.json z rejestru MCP. Obok konfiguracji plik .aggrega-config.yaml czyni z folderu obszar roboczy:
# 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 tworzy szkic encji Manifest na podstawie encji Recipes z katalogu. Przestrzeń robocza nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, którą pierwszy import pobiera, weryfikuje i przechowuje w pamięci podręcznej treści przestrzeni roboczej i którą rekord zapisywany przez import obok jego szkiców wskazuje za pomocą jej skrótu. Przestrzeń robocza, która wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub pod workspace.catalog_dirs — importuje zamiast tego względem nich.
Plik odpowiedzi
W Kubernetes serwer GitHub odczytuje swój token z obiektu Secret przechowywanego przez klaster, a żadna konfiguracja MCP nie wskazuje tego obiektu Secret: konfiguracja odczytuje token ze zmiennej GITHUB_TOKEN powłoki. Dlatego import pyta o nazwę obiektu Secret. Przykład przechowuje odpowiedź w import-answers.yaml, obok .mcp.json, gdzie import jej szuka:
# 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"Import sam zapisał ten plik przy pierwszym uruchomieniu bez odpowiedzi: nie mając terminala, w którym mógłby zapytać, utworzył szkic całej reszty, pozostawił pustą nazwę obiektu Secret, wymienił klucz w pliku i zatrzymał się z komunikatem
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 againW terminalu zamiast tego zadaje pytanie i zapisuje odpowiedź w pliku na potrzeby następnego importu. Odpowiedzią jest nazwa obiektu Secret, github-mcp-token, nigdy sam token. Plik odpowiedzi importu w pełni opisuje ten plik i pytania.
aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.
Należy przejść do source:
cd sourceUruchomienie importu
aggrega import .mcp.json --target helmNa standardowym wyjściu wymienia to, co zapisał:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:
[… 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)
Każdy serwer jest instancją narzędzia MCP z biblioteki standardowej, core/ai-tool/mcp, więc import nie rozważa żadnego kandydata i nie wypisuje żadnego wiersza mapped.
- Wiersze
warnwymieniają wartości, które zawiera konfiguracja serwera. Żaden klient MCP nie oznacza żadnej z nich jako poświadczenia, a każda z nich może je zawierać — klucz w argumencie wiersza poleceń, token w adresie — więc import wymienia każdy element wiersza poleceń, każdy nagłówek i każdy adres, który przeniósł, według jego serwera i miejsca, nigdy według wartości. Należy je przeczytać przed udostępnieniem szkicu. Wartość${GITHUB_TOKEN}wenvjest odwołaniem do zmiennej i niczym więcej, więc nie zawiera własnej wartości i żadne ostrzeżenie jej nie wymienia. - Wiersz
Pull completeoznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi toaggrega pull, dorelease.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z--offlineimport niczego nie pobiera i podaje polecenieaggrega pull, które należy uruchomić.
Co zapisuje import
Encje Aggregate, Release i Manifest otrzymują nazwę imported/mcp od pliku, .mcp.json, ponieważ konfiguracja klienta nie ma własnej nazwy — server.json rejestru otrzymuje nazwę od swojego name — w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).
aggregate.yaml — jedna instancja na serwer i jeszcze nic, co by z nich korzystało:
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 — jak każdy serwer jest uruchamiany lub osiągany, tak jak podaje to konfiguracja, oraz obiekt Secret, z którego odczytywany jest token serwera 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"- Środowisko,
development, to wartość domyślna, którą zapisuje import, ponieważ żadna konfiguracja go nie wskazuje; należy je zmienić, jeśli encja Release jest wdrażana gdzie indziej. stdio_runtimejest odczytywane z każdego polecenia:npxuruchamia pakiet npm,uvxpakiet PyPI.- Token GitHub. Środowisko serwera staje się jego slotem
server_env. W Kubernetes realizacjacore/referenced-secret-set, czylihelm/k8s-secret-set, zapisuje otrzymane wartości do obiektu Secret, który renderuje kompilacja, co umieściłoby token w pliku. Dlatego dla--target helmimport dołącza zamiast tegocore/referenced-secret, wskazując obiekt Secret, który klaster już przechowuje — odpowiedź,github-mcp-token— z jednym kluczem danych na zmienną,GITHUB_PERSONAL_ACCESS_TOKEN. Mostek importuje każdy klucz danych tego obiektu Secret jako zmienną o tej samej nazwie, więc serwer odczytuje swój token tak samo jak na komputerze użytkownika, a żaden wyrenderowany plik go nie zawiera. - Nagłówek
Authorizationpozostaje komentarzem. Poświadczenie zdalnego serwera przechowuje ten, kto go wywołuje, na własnym połączeniu tego wywołującego z narzędziem, a ten obszar roboczy nie ma jeszcze żadnego wywołującego. Po podłączeniu agenta dodocs-searchnagłówek trafia na to połączenie.
manifest.yaml — jedna realizacja na serwer, według jego nazwy, oraz realizacja obiektu 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-secretTrzy encje Recipes dla Kubernetes realizują core/ai-tool/mcp — jedna dla serwera opublikowanego jako obraz, jedna dla pakietu uruchamianego za mostkiem, jedna dla serwera prowadzonego przez kogoś innego — a to, która pasuje, jest właściwością każdego serwera, którą podaje konfiguracja. Dlatego import mapuje każdą instancję według nazwy: github i fetch, uruchamiane z wiersza poleceń, działają za mostkiem stdio, helm/mcp-stdio-bridge; docs-search, prowadzony przez kogoś innego, mapuje się na helm/mcp-remote, który niczego nie uruchamia i publikuje adres. Obiekt Secret tokenu mapuje się na helm/k8s-existing-secret, który odwołuje się do obiektu Secret zamiast go zapisywać.
release.lock rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.
W Docker Compose
Serwery działają także w Docker Compose. aggrega import .mcp.json --target compose mapuje github i fetch na compose/mcp-stdio-bridge, a docs-search na compose/mcp-remote, i zachowuje środowisko serwera GitHub tak, jak zapisuje je konfiguracja: wpis core/referenced-secret-set, którego wartością jest odwołanie do zmiennej ${GITHUB_TOKEN}, realizowany przez compose/dotenv-secret-set, który zapisuje je w niezmienionej postaci w środowisku usługi, dzięki czemu Docker Compose wypełnia je z powłoki przy uruchamianiu stosu. Ten import o nic nie pyta i zachowuje nazwę obiektu Secret w pliku odpowiedzi, nie używając jej.
Walidacja i kompilacja
aggrega validate --release release.yamlaggrega build --release release.yaml

Walidacja wypisuje:
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)oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:
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>/distWiersz notice ma charakter informacyjny: encja Feature przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat zgłasza, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia on żadnego werdyktu.
Kompilacja zapisuje w dist/helm/ obiekt Deployment i obiekt Service dla każdego z dwóch serwerów za mostkiem oraz jeden obiekt Service dla docs-search. Kontener serwera GitHub w dist/helm/github-deployment.yaml uruchamia mostek z wierszem poleceń serwera i pobiera swoje środowisko z obiektu 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 niczego nie uruchamia: nadaje serwerowi prowadzonemu przez kogoś innego nazwę wewnątrz klastra.
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: 443Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-mcp`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-mcp` i bez `dir`: zapisuje ono przykład w nowym folderze `import-mcp`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-mcp/source`, `source` ustawionym na `.mcp.json` i `target` ustawionym na `helm`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` obok `.mcp.json`, zapisuje szkice w `import-mcp/source` i pobiera to, czego potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-mcp/source` i `release` ustawionym na `release.yaml`, a potem narzędzie `build` z `workspace_root` ustawionym na `import-mcp/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj mi, które pliki zapisał build; znajdują się w `import-mcp/source/dist/`.Otwieranie w VS Code
Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-mcp/source, w którym import zapisał szkice. Folder zawiera jedną encję Release, szkic release.yaml, więc edytor sam ją wybiera i podczas edycji sprawdza szkice względem tej encji Release, zaznaczając to, co znajdzie, w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ tego folderu. Resztę opisuje Używanie Aggrega w Visual Studio Code.
Uruchomienie
Nic w wyniku budowania nie zapisuje obiektu Secret github-mcp-token, więc należy go utworzyć przed zastosowaniem plików. Należy zapisać token w github-token.env jako jeden wiersz GITHUB_PERSONAL_ACCESS_TOKEN=<your token> i utworzyć z niego obiekt Secret. Od tej chwili token przechowuje klaster, więc plik należy usunąć:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdNależy zastosować wynik budowania, jak wyjaśnia krok uruchamiania w Jak przebiega import, i poczekać na oba serwery:
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 metW Docker Compose, w obszarze roboczym zaimportowanym z --target compose i zbudowanym, należy uruchomić stos z tokenem w zmiennej GITHUB_TOKEN powłoki, którą Docker Compose odczytuje przy starcie stosu:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitTestowanie
Mostek udostępnia każdy serwer przez transport Streamable HTTP protokołu MCP, pod /mcp na porcie 8080. Należy poprosić serwer fetch o otwarcie sesji żądaniem initialize protokołu MCP, które nie odczytuje żadnego tokenu.
W Docker Compose należy wysłać je z jednorazowego kontenera w sieci stosu, mcp_compose, w której serwer nazywa się 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"}}}W Kubernetes należy przekierować port lokalny do obiektu Service serwera, fetch-default, i pozostawić polecenie uruchomione:
kubectl port-forward svc/fetch-default 8080:8080Z innego terminala należy wysłać to samo żądanie na przekierowany port:
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"}}}Odpowiedź podaje nazwę serwera, mcp-fetch. Trwa to chwilę: mostek uruchamia dla każdej sesji wiersz poleceń serwera, uvx mcp-server-fetch, a uvx najpierw pobiera i instaluje pakiety serwera — w tym uruchomieniu około pół minuty w Kubernetes i około minuty w Docker Compose. Wiersze : keepalive to komentarze, które strumień wysyła w międzyczasie.
Serwer GitHub odpowiada na to samo żądanie pod http://github:8080/mcp w Docker Compose oraz przez kubectl port-forward svc/github-default 8080:8080 w Kubernetes. initialize nie odczytuje żadnego tokenu, więc odpowiada niezależnie od zawartości tokenu; uruchomienie użyło tokenu zastępczego:
[… 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}Należy zatrzymać przekierowanie portu, a następnie usunąć to, co zostało zastosowane, oraz obiekt Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenW Docker Compose należy zatrzymać i usunąć stos:
docker compose -p mcp -f dist/compose/docker-compose.yaml down