Eine MCP-Client-Konfiguration importieren
Diese Schritt-für-Schritt-Anleitung importiert die Model-Context-Protocol-Server, mit denen ein Coding-Assistent konfiguriert ist — zwei, die er über eine Befehlszeile startet, und einen, den jemand anderes betreibt —, und baut die Server für Kubernetes, sodass ein in einem Cluster laufender Agent dieselben Tools erreichen kann. Der Import entwirft jede Datei, die der Build liest: die Befehlszeile oder Adresse jedes Servers, die Realisierung, die ihn ausführt, und woher das Token des GitHub-Servers kommt. Jede Datei und jeder Ausgabeblock unten stammt aus einem echten Lauf; die Konfiguration und jede Phase der Anleitung befinden sich im Beispiel import-mcp, in dem ein Prüfskript den Import erneut ausführt, das, was er schreibt, was er ausgibt, und die Blöcke, die diese Seite zitiert, mit den dort abgelegten Dateien vergleicht und das, was der Import geschrieben hat, validiert und baut.
Das Beispiel generieren
Sie können diesen Import mit den Befehlen auf dieser Seite ausführen oder ihn von Ihrem KI-Assistenten ausführen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example import-mcpDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner; der folgende, unten, wechselt in den Ordner source des neuen Ordners, der enthält, was diese Seite importiert, und in dem der Import läuft:
cd import-mcp
Die Konfiguration
Die .mcp.json von Claude Code, im Stammverzeichnis eines Projekts:
{ "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}" } } }}Der Import liest die claude_desktop_config.json von Claude Desktop, die .cursor/mcp.json von Cursor, die .vscode/mcp.json von Visual Studio Code und eine server.json einer MCP-Registry auf dieselbe Weise. Neben der Konfiguration macht eine .aggrega-config.yaml den Ordner zu einem Workspace:
# 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 entwirft ein Manifest aus den Recipes des Katalogs. Der Arbeitsbereich nennt keinen Katalogordner, daher liest der Import den Katalog der Standardbibliothek aus der Registry, aus der er seinen Importer holt: einen signierten Snapshot des veröffentlichten Katalogs, den der erste Import holt, verifiziert und im Inhalts-Cache des Arbeitsbereichs ablegt und den die Aufzeichnung, die der Import neben seine Entwürfe schreibt, über seinen Digest benennt. Ein Arbeitsbereich, der eigene Katalogordner nennt — in AGGREGA_CATALOG_DIRS oder unter workspace.catalog_dirs —, importiert stattdessen gegen diese.
Die Antwortdatei
Auf Kubernetes liest der GitHub-Server sein Token aus einem Secret, das der Cluster vorhält, und keine MCP-Konfiguration nennt dieses Secret: Die Konfiguration liest das Token aus der Variable GITHUB_TOKEN Ihrer Shell. Daher fragt der Import nach dem Namen des Secret. Das Beispiel bewahrt die Antwort in import-answers.yaml auf, neben .mcp.json, wo der Import sie sucht:
# 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"Der Import hat die Datei selbst geschrieben, als er zum ersten Mal ohne Antwort ausgeführt wurde: Ohne Terminal, an dem er fragen konnte, entwarf er alles Übrige, ließ den Namen des Secret leer, führte den Schlüssel in der Datei auf und hielt an mit
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 againAn einem Terminal stellt er stattdessen die Frage und schreibt die Antwort für den nächsten Import in die Datei. Die Antwort ist der Name des Secret, github-mcp-token, niemals das Token. Die Antwortdatei des Imports beschreibt die Datei und die Fragen vollständig.
aggrega import listet jedes Flag auf, das der Befehl annimmt, darunter --answers, das eine anderswo abgelegte Antwortdatei nennt.
Wechseln Sie in source:
cd sourceDen Import ausführen
aggrega import .mcp.json --target helmAuf der Standardausgabe listet er auf, was er geschrieben hat:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonAuf der Standardfehlerausgabe, wobei <workspace> für den Ordner steht, in dem Sie ihn ausgeführt haben:
[… 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)
Jeder Server ist eine Instanz des MCP-Tools der Standardbibliothek, core/ai-tool/mcp, daher wägt der Import keinen Kandidaten ab und gibt keine Zeile mapped aus.
- Die Zeilen
warnnennen die Werte, die die Konfiguration eines Servers enthält. Kein MCP-Client kennzeichnet einen davon als Anmeldeinformation, und jeder davon kann eine enthalten — ein Schlüssel in einem Befehlszeilenargument, ein Token in einer Adresse —, daher nennt der Import jedes Element einer Befehlszeile, jeden Header und jede Adresse, die er übernommen hat, anhand ihres Servers und ihrer Stelle, niemals anhand ihres Werts. Lesen Sie sie, bevor Sie den Entwurf teilen. Der Wert${GITHUB_TOKEN}unterenvist eine Variablenreferenz und nichts anderes, daher enthält er keinen eigenen Wert und keine Warnung nennt ihn. - Die Zeile
Pull completezeigt, dass der Import das, wovon das entworfene Release abhängt, wieaggrega pullinrelease.lockabruft, sodass die Entwürfe sofort validiert und gebaut werden können. Mit--offlineruft der Import nichts ab und nennt den auszuführenden Befehlaggrega pull.
Was er schreibt
Das Aggregate, das Release und das Manifest heißen imported/mcp, nach der Datei, .mcp.json, da die Konfiguration eines Clients keinen eigenen Namen trägt — die server.json einer Registry wird nach ihrem name benannt —, unter dem Namespace, den die Einstellung target_namespace des Importers festlegt, imported, sofern Sie keinen anderen festlegen (Einstellungen).
aggregate.yaml — eine Instanz pro Server und noch nichts, das sie verwendet:
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 — wie jeder Server ausgeführt oder erreicht wird, so wie die Konfiguration es angibt, und das Secret, aus dem das Token des GitHub-Servers gelesen wird:
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"- Die Umgebung,
development, ist ein Standardwert, den der Import schreibt, weil keine Konfiguration eine nennt; ändern Sie sie, wenn das Release anderswo bereitgestellt wird. stdio_runtimewird aus jedem Befehl abgelesen:npxführt ein npm-Paket aus,uvxein PyPI-Paket.- Das GitHub-Token. Die Umgebung des Servers wird zu seinem Slot
server_env. Auf Kubernetes schreibt die Realisierung voncore/referenced-secret-set,helm/k8s-secret-set, die Werte, die sie erhält, in ein Secret, das der Build rendert, wodurch das Token in einer Datei landen würde. Deshalb hängt der Import für--target helmstattdessencore/referenced-secretan, das ein Secret nennt, das der Cluster bereits enthält — die Antwort,github-mcp-token— mit einem Datenschlüssel pro Variable,GITHUB_PERSONAL_ACCESS_TOKEN. Die Bridge importiert jeden Datenschlüssel dieses Secrets als Variable gleichen Namens, sodass der Server sein Token so liest, wie er es auf Ihrem Rechner tat, und keine gerenderte Datei es enthält. - Der Header
Authorizationbleibt ein Kommentar. Die Anmeldeinformation eines entfernten Servers hält derjenige, der ihn aufruft, auf der eigenen Verbindung dieses Aufrufers zum Tool, und dieser Workspace hat noch keinen Aufrufer. Wenn Sie einen Agenten mitdocs-searchverdrahten, gehört der Header auf diese Verbindung.
manifest.yaml — eine Realisierung pro Server, anhand seines Namens, und die Realisierung des Secrets:
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-secretDrei Recipes für Kubernetes realisieren core/ai-tool/mcp — eines für einen als Image veröffentlichten Server, eines für ein Paket, das hinter einer Bridge läuft, eines für einen Server, den jemand anderes betreibt —, und welches passt, ist eine Eigenschaft jedes Servers, die die Konfiguration angibt. Deshalb bildet der Import jede Instanz anhand ihres Namens ab: github und fetch, über eine Befehlszeile gestartet, laufen hinter der stdio-Bridge, helm/mcp-stdio-bridge; docs-search, das jemand anderes betreibt, wird auf helm/mcp-remote abgebildet, das nichts ausführt und die Adresse veröffentlicht. Das Secret des Tokens wird auf helm/k8s-existing-secret abgebildet, das ein Secret referenziert, statt eines zu schreiben.
release.lock hält per Digest die Katalog-Entitäten fest, zu denen das Release aufgelöst wurde, und .aggrega-import.json ist die Aufzeichnung dessen, was der Import geschrieben hat, und wird von einem späteren aggrega import --sync gelesen.
Auf Docker Compose
Die Server laufen auch auf Docker Compose. aggrega import .mcp.json --target compose bildet github und fetch auf compose/mcp-stdio-bridge und docs-search auf compose/mcp-remote ab und behält die Umgebung des GitHub-Servers so bei, wie die Konfiguration sie schreibt: einen Eintrag von core/referenced-secret-set, dessen Wert die Variablenreferenz ${GITHUB_TOKEN} ist, realisiert durch compose/dotenv-secret-set, das sie unverändert in die Umgebung des Dienstes schreibt, sodass Docker Compose sie beim Start des Stacks aus Ihrer Shell befüllt. Dieser Import fragt nichts ab und behält den Namen des Secrets in der Antwortdatei, ohne ihn zu verwenden.
Validieren und bauen
aggrega validate --release release.yamlaggrega build --release release.yaml

Die Validierung gibt aus:
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)und der Build, wobei <workspace> für den Ordner steht, in dem Sie ihn ausgeführt haben:
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>/distDie Zeile notice ist rein informativ: Das Feature akzeptiert sein origin aus den values des Aggregate oder aus der infra des Release, und der Hinweis meldet, dass ein Blatt in beiden deklariert ist. Sie ändert kein Urteil.
Der Build schreibt unter dist/helm/ ein Deployment und einen Service für jeden der beiden über die Bridge angebundenen Server sowie einen Service für docs-search. Der Container des GitHub-Servers, in dist/helm/github-deployment.yaml, führt die Bridge mit der Befehlszeile des Servers aus und bezieht seine Umgebung aus dem 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 führt nichts aus: Es gibt dem Server, den jemand anderes betreibt, einen Namen innerhalb des Clusters.
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: 443Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie diesen Prompt dort ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `import-mcp` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `import-mcp` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `import-mcp`, dessen Ordner `source` enthält, was diese Seite importiert. Rufen Sie dann das Tool `import` auf, mit `workspace_root` auf `import-mcp/source`, `source` auf `.mcp.json` und `target` auf `helm` gesetzt: Es liest die benötigten Antworten aus `import-answers.yaml` neben `.mcp.json`, schreibt seine Entwürfe nach `import-mcp/source` und zieht, was sie benötigen. Rufen Sie dann das Tool `validate` auf, mit `workspace_root` auf `import-mcp/source` und `release` auf `release.yaml` gesetzt, und das Tool `build`, mit `workspace_root` auf `import-mcp/source`, `release` auf `release.yaml` und `write` auf true gesetzt. Sagen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `import-mcp/source/dist/`.In VS Code öffnen
Wenn die Aggrega-Erweiterung für Visual Studio Code installiert ist, öffnen Sie in VS Code den Ordner import-mcp/source, in den der Import seine Entwürfe geschrieben hat. Der Ordner enthält ein Release, das entworfene release.yaml, daher wählt der Editor es für Sie aus und prüft die Entwürfe beim Bearbeiten gegen dieses Release, wobei er seine Befunde in der Datei und im Bereich Probleme markiert. Aggrega: Show topology graph in der Befehlspalette zeichnet die Komponenten des Release und die Verbindungen zwischen ihnen. Aggrega: Build, Aggrega: Preview build und Aggrega: Pull wirken auf dasselbe Release, und jeder ist auch eine Schaltfläche im Bereich Commands der Ansicht Aggrega in der Aktivitätsleiste; Build schreibt seine Dateien in dist/ des Ordners. Aggrega in Visual Studio Code verwenden behandelt den Rest.
Ausführen
Nichts im Build schreibt das Secret github-mcp-token, erstellen Sie es daher, bevor Sie die Dateien anwenden. Schreiben Sie Ihr Token in github-token.env, als die eine Zeile GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, und erstellen Sie daraus das Secret. Der Cluster hält das Token dann, löschen Sie also die Datei:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdWenden Sie den Build an, wie der Ausführungsschritt von Wie ein Import abläuft erklärt, und warten Sie auf die beiden Server:
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 metStarten Sie auf Docker Compose, in einem mit --target compose importierten und gebauten Workspace, den Stack mit Ihrem Token in GITHUB_TOKEN Ihrer Shell, das Docker Compose beim Start des Stacks liest:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitTesten
Die Bridge stellt jeden Server über den Transport Streamable HTTP von MCP bereit, unter /mcp auf Port 8080. Bitten Sie den Server fetch mit der MCP-Anfrage initialize, die kein Token liest, eine Sitzung zu öffnen.
Senden Sie sie auf Docker Compose aus einem Wegwerf-Container im Netzwerk des Stacks, mcp_compose, in dem der Server fetch heißt:
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"}}}Leiten Sie auf Kubernetes einen lokalen Port an den Service des Servers, fetch-default, weiter und lassen Sie den Befehl laufen:
kubectl port-forward svc/fetch-default 8080:8080Senden Sie von einem anderen Terminal aus dieselbe Anfrage an den weitergeleiteten 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"}}}Die Antwort nennt den Server, mcp-fetch. Sie dauert eine Weile: Die Bridge startet für jede Sitzung die Befehlszeile des Servers, uvx mcp-server-fetch, und uvx lädt zuerst die Pakete des Servers herunter und installiert sie — im Lauf etwa eine halbe Minute auf Kubernetes und etwa eine Minute auf Docker Compose. Die Zeilen : keepalive sind Kommentare, die der Stream in der Zwischenzeit sendet.
Der GitHub-Server beantwortet dieselbe Anfrage unter http://github:8080/mcp auf Docker Compose und über kubectl port-forward svc/github-default 8080:8080 auf Kubernetes. initialize liest kein Token, daher antwortet er unabhängig davon, was das Token enthält; der Lauf verwendete ein Platzhalter-Token:
[… 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}Beenden Sie die Portweiterleitung und entfernen Sie dann, was Sie angewendet haben, sowie das Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenStoppen und entfernen Sie auf Docker Compose den Stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml down