Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

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 :

Terminal window
aggrega scaffold --example import-mcp

Elle 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 :

Terminal window
cd import-mcp

Le dossier source de l’exemple généré ouvert dans Visual Studio Code, montrant sa configuration MCP avec trois serveurs : github, fetch et docs-search.

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 again

Dans 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 :

Terminal window
cd source

Lancer l’importation

Terminal window
aggrega import .mcp.json --target helm

Sur la sortie standard, elle liste ce qu’elle a écrit :

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sur 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 empty
warn: 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 empty
warn: 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 empty
warn: 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 empty
warn: 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 empty
warn: 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 empty
warn: 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 empty
Pull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)

L’importation lancée depuis l’éditeur : l’Aggregate, la Release et le Manifest ébauchés apparaissent à côté de la configuration MCP, la sortie Aggrega liste les valeurs reprises telles qu’écrites et les fichiers écrits, et une notification indique que l’importation a ébauché 3 fichiers, reconnus comme mcp.

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 warn nomment 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} de env est 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 complete correspond à l’import qui récupère ce dont dépend la Release rédigée, comme le fait aggrega pull, dans release.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 commande aggrega 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/v1beta1
kind: Aggregate
metadata:
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/mcp

release.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/v1beta1
kind: Release
metadata:
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_runtime est déduit de chaque commande : npx exécute un paquet npm, uvx un paquet PyPI.
  • Le jeton GitHub. L’environnement du serveur devient son emplacement server_env. Sur Kubernetes, la réalisation de core/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ôt core/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 Authorization reste 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/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
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

Trois 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

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release ébauchée ouverte dans l’éditeur après sa validation, la sortie Aggrega et une notification ne signalant toutes deux aucun problème.

Le build de la Release ébauchée : un dossier dist apparaît dans l’explorateur, la sortie Aggrega liste un Deployment et un Service pour chaque serveur, et une notification indique que 5 fichiers ont été écrits.

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>/dist

La 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: v1
kind: Service
metadata:
name: docs-search
[… omitted: the labels and annotations the build writes on every resource]
spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

Avec 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 :

Terminal window
kubectl create secret generic github-mcp-token --from-env-file=github-token.env
rm github-token.env
secret/github-mcp-token created

Appliquez le build, comme l’explique l’étape d’exécution de Déroulement d’une importation, et attendez les deux serveurs :

Terminal window
kubectl apply -R -f dist/helm/
kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5m
service/docs-search created
service/fetch-default created
deployment.apps/fetch created
service/github-default created
deployment.apps/github created
deployment.apps/fetch condition met
deployment.apps/github condition met

Sur 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 :

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --wait

Tester

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 :

Terminal window
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: message
data: {"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 :

Terminal window
kubectl port-forward svc/fetch-default 8080:8080

Depuis un autre terminal, envoyez la même requête au port redirigé :

Terminal window
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: message
data: {"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: message
data: {"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 :

Terminal window
kubectl delete -R -f dist/helm/
kubectl delete secret github-mcp-token

Sur Docker Compose, arrêtez et supprimez la pile :

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml down