Importer la configuration d’un client MCP
Ce tutoriel pas à pas importe les serveurs Model Context Protocol avec lesquels un assistant de programmation est configuré — deux qu’il démarre à partir d’une ligne de commande et un que quelqu’un d’autre exécute — et construit les serveurs pour Kubernetes, afin qu’un agent s’exécutant dans un cluster puisse atteindre les mêmes outils. L’import rédige en brouillon chaque fichier que le build lit : la ligne de commande ou l’adresse de chaque serveur, la réalisation qui l’exécute et la provenance du jeton du serveur GitHub. Chaque fichier et chaque bloc de sortie ci-dessous proviennent d’une exécution réelle ; la configuration et chaque étape du tutoriel se trouvent dans l’exemple import-mcp, où un script de vérification relance l’import, compare ce qu’il écrit, ce qu’il affiche et les blocs que cite cette page avec les fichiers qui y sont conservés, puis valide et construit ce que l’import a écrit.
Générer l’exemple
Vous pouvez exécuter cette importation avec les commandes de cette page, ou la faire exécuter par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example import-mcpElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier ; la suivante, ci-dessous, vous place dans le dossier source du nouveau dossier, qui contient ce que cette page importe et où s’exécute l’import :
cd import-mcp
La configuration
Le .mcp.json de Claude Code, à la racine d’un projet :
{ "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}" } } }}L’import lit de la même manière le claude_desktop_config.json de Claude Desktop, le .cursor/mcp.json de Cursor, le .vscode/mcp.json de Visual Studio Code et un server.json de registre MCP. À côté de la configuration, un .aggrega-config.yaml fait du dossier un espace de travail :
# 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 rédige un brouillon de Manifest à partir des Recipes du catalogue. L’espace de travail n’indique aucun dossier de catalogue ; l’import lit donc le catalogue de la bibliothèque standard depuis le registre dont il récupère son importateur : un instantané signé du catalogue publié, que le premier import récupère, vérifie et conserve dans le cache de contenu de l’espace de travail, et que l’enregistrement écrit par l’import à côté de ses brouillons désigne par son condensé. Un espace de travail qui indique ses propres dossiers de catalogue — dans AGGREGA_CATALOG_DIRS, ou sous workspace.catalog_dirs — importe plutôt en s’appuyant sur ceux-ci.
Le fichier de réponses
Sur Kubernetes, le serveur GitHub lit son jeton dans un Secret que détient le cluster, et aucune configuration MCP ne nomme ce Secret : la configuration lit le jeton dans la variable GITHUB_TOKEN de votre shell. L’import demande donc le nom du Secret. L’exemple conserve la réponse dans import-answers.yaml, à côté de .mcp.json, là où l’import la cherche :
# 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"L’import a écrit le fichier lui-même, la première fois qu’il a été exécuté sans réponse : faute de terminal où poser la question, il a rédigé tout le reste, laissé vide le nom du Secret, répertorié la clé dans le fichier, et s’est arrêté avec
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 againDans un terminal, il pose plutôt la question, et écrit la réponse dans le fichier pour l’import suivant. La réponse est le nom du Secret, github-mcp-token, jamais le jeton. Le fichier de réponses de l’import décrit en détail le fichier et les questions.
aggrega import liste toutes les options que prend la commande, dont --answers, qui nomme un fichier de réponses conservé ailleurs.
Placez-vous dans source :
cd sourceLancer l’importation
aggrega import .mcp.json --target helmSur la sortie standard, elle liste ce qu’elle a écrit :
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonSur la sortie d’erreur standard, où <workspace> désigne le dossier dans lequel vous l’avez lancée :
[… 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)
Chaque serveur est une instance de l’outil MCP de la bibliothèque standard, core/ai-tool/mcp, si bien que l’import n’évalue aucun candidat et n’affiche aucune ligne mapped.
- Les lignes
warnnomment les valeurs que contient la configuration d’un serveur. Aucun client MCP n’en marque aucune comme information d’identification, et chacune peut en porter une — une clé dans un argument de ligne de commande, un jeton dans une adresse —, si bien que l’import nomme chaque élément d’une ligne de commande, chaque en-tête et chaque adresse qu’il a repris, par son serveur et sa position, jamais par sa valeur. Lisez-les avant de partager le brouillon. La valeur${GITHUB_TOKEN}deenvest une référence de variable et rien d’autre, elle ne contient donc aucune valeur propre et aucun avertissement ne la nomme. - La ligne
Pull completecorrespond à l’import qui récupère ce dont dépend la Release rédigée, comme le faitaggrega pull, dansrelease.lock, de sorte que les brouillons se valident et se construisent immédiatement. Avec--offline, l’import ne récupère rien et indique la commandeaggrega pullà exécuter.
Ce qu’elle écrit
L’Aggregate, la Release et le Manifest sont nommés imported/mcp, d’après le fichier, .mcp.json, puisque la configuration d’un client ne porte pas de nom propre — le server.json d’un registre est nommé d’après son name —, sous le namespace que fixe le paramètre target_namespace de l’importeur, imported sauf si vous en fixez un autre (Paramètres).
aggregate.yaml — une instance par serveur, et encore rien qui les utilise :
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 — la façon dont chaque serveur est exécuté ou atteint, telle que la configuration l’indique, et le Secret dans lequel est lu le jeton du serveur 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"- L’environnement,
development, est une valeur par défaut que l’import écrit parce qu’aucune configuration n’en nomme un ; modifiez-le si la Release est déployée ailleurs. stdio_runtimeest déduit de chaque commande :npxexécute un paquet npm,uvxun paquet PyPI.- Le jeton GitHub. L’environnement du serveur devient son emplacement
server_env. Sur Kubernetes, la réalisation decore/referenced-secret-set,helm/k8s-secret-set, écrit les valeurs qu’elle reçoit dans un Secret que le build rend, ce qui placerait le jeton dans un fichier. Pour--target helm, l’import attache donc plutôtcore/referenced-secret, qui nomme un Secret que le cluster détient déjà — la réponse,github-mcp-token— avec une clé de données par variable,GITHUB_PERSONAL_ACCESS_TOKEN. La passerelle importe chaque clé de données de ce Secret comme une variable du même nom, de sorte que le serveur lit son jeton comme il le faisait sur votre machine, et qu’aucun fichier rendu ne le contient. - L’en-tête
Authorizationreste un commentaire. L’information d’identification d’un serveur distant est détenue par celui qui l’appelle, sur la propre connexion de cet appelant à l’outil, et cet espace de travail n’a encore aucun appelant. Lorsque vous reliez un agent àdocs-search, l’en-tête va sur cette connexion.
manifest.yaml — une réalisation par serveur, d’après son nom, et la réalisation du 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-secretTrois Recipes Kubernetes réalisent core/ai-tool/mcp — une pour un serveur publié sous forme d’image, une pour un paquet exécuté derrière une passerelle, une pour un serveur que quelqu’un d’autre exécute — et celle qui convient est une propriété de chaque serveur, que la configuration indique. L’import mappe donc chaque instance par son nom : github et fetch, démarrés à partir d’une ligne de commande, s’exécutent derrière la passerelle stdio, helm/mcp-stdio-bridge ; docs-search, que quelqu’un d’autre exécute, est mappé sur helm/mcp-remote, qui n’exécute rien et publie l’adresse. Le Secret du jeton est mappé sur helm/k8s-existing-secret, qui référence un Secret plutôt que d’en écrire un.
release.lock enregistre, par digest, les entités du catalogue vers lesquelles la Release a été résolue, et .aggrega-import.json est l’enregistrement de ce que l’importation a écrit, que lit un aggrega import --sync ultérieur.
Sur Docker Compose
Les serveurs s’exécutent aussi sur Docker Compose. aggrega import .mcp.json --target compose mappe github et fetch sur compose/mcp-stdio-bridge et docs-search sur compose/mcp-remote, et conserve l’environnement du serveur GitHub tel que la configuration l’écrit : une entrée de core/referenced-secret-set dont la valeur est la référence de variable ${GITHUB_TOKEN}, réalisée par compose/dotenv-secret-set, qui l’écrit telle quelle dans l’environnement du service, de sorte que Docker Compose la renseigne depuis votre shell au démarrage de la pile. Cet import ne demande rien et conserve le nom du Secret dans le fichier de réponses sans l’utiliser.
Valider et compiler
aggrega validate --release release.yamlaggrega build --release release.yaml

La validation affiche :
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)et le build, où <workspace> désigne le dossier dans lequel vous l’avez exécuté :
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>/distLa ligne notice est indicative : la Feature accepte son origin depuis les values de l’Aggregate ou depuis l’infra de la Release, et l’avis signale qu’une feuille est déclarée dans les deux. Elle ne change aucun verdict.
Le build écrit, sous dist/helm/, un Deployment et un Service pour chacun des deux serveurs placés derrière la passerelle, et un Service pour docs-search. Le conteneur du serveur GitHub, dans dist/helm/github-deployment.yaml, exécute la passerelle avec la ligne de commande du serveur, et prend son environnement depuis le 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 n’exécute rien : il donne au serveur que quelqu’un d’autre exécute un nom à l’intérieur du cluster.
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: 443Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.
Utilise uniquement les outils Aggrega et ne crée aucun dossier toi-même. Si le dossier de l’espace de travail ne contient pas encore de dossier `import-mcp`, appelle une fois l’outil `scaffold` avec `example` défini sur `import-mcp` et sans `dir` : il écrit l’exemple dans un nouveau dossier `import-mcp`, dont le dossier `source` contient ce que cette page importe. Appelle ensuite l’outil `import` avec `workspace_root` défini sur `import-mcp/source`, `source` défini sur `.mcp.json` et `target` défini sur `helm` : il lit les réponses dont il a besoin dans `import-answers.yaml` à côté de `.mcp.json`, écrit ses ébauches dans `import-mcp/source` et tire ce dont elles ont besoin. Appelle ensuite l’outil `validate` avec `workspace_root` défini sur `import-mcp/source` et `release` défini sur `release.yaml`, puis l’outil `build` avec `workspace_root` défini sur `import-mcp/source`, `release` défini sur `release.yaml` et `write` défini sur true. Dis-moi quels fichiers le build a écrits ; ils se trouvent sous `import-mcp/source/dist/`.L’ouvrir dans VS Code
Une fois l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le dossier import-mcp/source, où l’importation a écrit ses ébauches. Le dossier contient une seule Release, le release.yaml ébauché ; l’éditeur la sélectionne donc pour vous et vérifie les ébauches par rapport à cette Release pendant que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du dossier. Utiliser Aggrega dans Visual Studio Code couvre le reste.
Exécution
Rien dans le build n’écrit le Secret github-mcp-token ; créez-le donc avant d’appliquer les fichiers. Écrivez votre jeton dans github-token.env, sous la forme de l’unique ligne GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, et créez le Secret à partir de celui-ci. Le cluster détient alors le jeton ; supprimez donc le fichier :
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdAppliquez le build, comme l’explique l’étape d’exécution de Déroulement d’une importation, et attendez les deux serveurs :
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 metSur Docker Compose, dans un espace de travail importé avec --target compose puis construit, démarrez la pile avec votre jeton dans la variable GITHUB_TOKEN de votre shell, que Docker Compose lit au démarrage de la pile :
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitTester
La passerelle sert chaque serveur via le transport Streamable HTTP de MCP, sur /mcp au port 8080. Demandez au serveur fetch d’ouvrir une session avec la requête initialize de MCP, qui ne lit aucun jeton.
Sur Docker Compose, envoyez-la depuis un conteneur jetable sur le réseau de la pile, mcp_compose, où le nom du serveur est 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"}}}Sur Kubernetes, redirigez un port local vers le Service du serveur, fetch-default, et laissez la commande s’exécuter :
kubectl port-forward svc/fetch-default 8080:8080Depuis un autre terminal, envoyez la même requête au port redirigé :
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"}}}La réponse nomme le serveur, mcp-fetch. Elle prend un certain temps : la passerelle démarre la ligne de commande du serveur, uvx mcp-server-fetch, pour chaque session, et uvx télécharge et installe d’abord les paquets du serveur — environ une demi-minute sur Kubernetes et environ une minute sur Docker Compose lors de l’exécution. Les lignes : keepalive sont des commentaires que le flux envoie entre-temps.
Le serveur GitHub répond à la même requête sur http://github:8080/mcp sous Docker Compose, et via kubectl port-forward svc/github-default 8080:8080 sous Kubernetes. initialize ne lit aucun jeton ; il répond donc quel que soit le contenu du jeton. L’exécution a utilisé un jeton fictif :
[… 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}Arrêtez la redirection de port, puis supprimez ce que vous avez appliqué ainsi que le Secret :
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenSur Docker Compose, arrêtez et supprimez la pile :
docker compose -p mcp -f dist/compose/docker-compose.yaml down