Importar la configuración de un cliente MCP
Este recorrido guiado importa los servidores Model Context Protocol con los que está configurado un asistente de programación — dos que inicia desde una línea de comandos y uno que ejecuta otra persona — y compila los servidores para Kubernetes, de modo que un agente que se ejecuta en un clúster pueda llegar a las mismas herramientas. La importación genera como borrador cada archivo que lee la compilación: la línea de comandos o la dirección de cada servidor, la realización que lo ejecuta y de dónde viene el token del servidor de GitHub. Cada archivo y cada bloque de salida que aparecen a continuación provienen de una ejecución real; la configuración y cada etapa del recorrido están en el ejemplo import-mcp, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos que se conservan allí, y valida y compila lo que la importación escribió.
Generar el ejemplo
Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example import-mcpDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, que contiene lo que esta página importa y es donde se ejecuta la importación:
cd import-mcp
La configuración
El .mcp.json de Claude Code, en la raíz de un proyecto:
{ "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}" } } }}La importación lee de la misma forma el claude_desktop_config.json de Claude Desktop, el .cursor/mcp.json de Cursor, el .vscode/mcp.json de Visual Studio Code y un server.json de un registro MCP. Junto a la configuración, un .aggrega-config.yaml convierte la carpeta en un espacio de trabajo:
# 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 genera un borrador de Manifest a partir de las Recipes del catálogo. El espacio de trabajo no indica ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar desde el registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que el historial que la importación escribe junto a sus borradores nombra por su resumen criptográfico. Un espacio de trabajo que indica sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS, o bajo workspace.catalog_dirs — importa en cambio a partir de ellas.
El archivo de respuestas
En Kubernetes, el servidor de GitHub lee su token de un Secret que guarda el clúster, y ninguna configuración MCP nombra ese Secret: la configuración lee el token de la variable GITHUB_TOKEN de tu shell. Por eso la importación pregunta el nombre del Secret. El ejemplo guarda la respuesta en import-answers.yaml, junto a .mcp.json, donde la importación la busca:
# 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"La importación escribió el archivo ella misma, la primera vez que se ejecutó sin respuesta: sin un terminal en el que preguntar, generó el borrador de todo lo demás, dejó vacío el nombre del Secret, incluyó la clave en el archivo y se detuvo con
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 againEn un terminal, en cambio, hace la pregunta y escribe la respuesta en el archivo para la siguiente importación. La respuesta es el nombre del Secret, github-mcp-token, nunca el token. El archivo de respuestas de la importación describe por completo el archivo y las preguntas.
aggrega import enumera cada opción que admite el comando, entre ellas --answers, que nombra un archivo de respuestas guardado en otro lugar.
Entra en source:
cd sourceEjecutar la importación
aggrega import .mcp.json --target helmEn la salida estándar enumera lo que escribió:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonEn la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:
[… 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)
Cada servidor es una instancia de la herramienta MCP de la biblioteca estándar, core/ai-tool/mcp, así que la importación no sopesa ningún candidato y no imprime ninguna línea mapped.
- Las líneas
warnnombran los valores que contiene la configuración de un servidor. Ningún cliente MCP marca ninguno de ellos como credencial, y cualquiera puede contener una — una clave en un argumento de la línea de comandos, un token en una dirección —, así que la importación nombra cada elemento de una línea de comandos, cada cabecera y cada dirección que contenía, por su servidor y su posición, nunca por su valor. Léelos antes de compartir el borrador. El valor${GITHUB_TOKEN}deenves una referencia a una variable y nada más, así que no contiene ningún valor propio y ninguna advertencia lo nombra. - La línea
Pull completees la importación obteniendo aquello de lo que depende la Release redactada, como haceaggrega pull, enrelease.lock, para que los borradores se validen y se compilen de inmediato. Con--offline, la importación no obtiene nada e indica el comandoaggrega pullque hay que ejecutar.
Lo que escribe
El Aggregate, la Release y el Manifest se llaman imported/mcp, por el archivo, .mcp.json, ya que la configuración de un cliente no lleva nombre propio — el server.json de un registro recibe el nombre de su name — bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).
aggregate.yaml — una instancia por servidor, y todavía nada que las use:
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 — cómo se ejecuta o se alcanza cada servidor, tal como lo indica la configuración, y el Secret del que se lee el token del servidor de 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"- El entorno,
development, es un valor predeterminado que la importación escribe porque ninguna configuración nombra uno; cámbialo si la Release se despliega en otro lugar. stdio_runtimese deduce de cada comando:npxejecuta un paquete npm,uvxuno de PyPI.- El token de GitHub. El entorno del servidor se convierte en su ranura
server_env. En Kubernetes, la realización decore/referenced-secret-set,helm/k8s-secret-set, escribe los valores que recibe en un Secret que la compilación renderiza, lo que pondría el token en un archivo. Por eso, para--target helmla importación adjunta en su lugarcore/referenced-secret, que nombra un Secret que el clúster ya contiene — la respuesta,github-mcp-token— con una clave de datos por variable,GITHUB_PERSONAL_ACCESS_TOKEN. El puente importa cada clave de datos de ese Secret como una variable del mismo nombre, así que el servidor lee su token como lo hacía en tu máquina, y ningún archivo renderizado lo contiene. - La cabecera
Authorizationsigue siendo un comentario. La credencial de un servidor remoto la tiene quien lo llama, en la propia conexión de ese llamador con la herramienta, y este espacio de trabajo aún no tiene ningún llamador. Cuando conectes un agente adocs-search, la cabecera va en esa conexión.
manifest.yaml — una realización por servidor, según su nombre, y la realización del 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-secretTres Recipes de Kubernetes realizan core/ai-tool/mcp — una para un servidor publicado como imagen, una para un paquete que se ejecuta detrás de un puente, una para un servidor que ejecuta otra persona — y cuál encaja es una propiedad de cada servidor, que la configuración indica. Por eso la importación mapea cada instancia por su nombre: github y fetch, iniciados desde una línea de comandos, se ejecutan detrás del puente stdio, helm/mcp-stdio-bridge; docs-search, que ejecuta otra persona, se mapea a helm/mcp-remote, que no ejecuta nada y publica la dirección. El Secret del token se mapea a helm/k8s-existing-secret, que hace referencia a un Secret en lugar de escribir uno.
release.lock registra, por digest, las entidades del catálogo a las que se resolvió la Release, y .aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior.
En Docker Compose
Los servidores también se ejecutan en Docker Compose. aggrega import .mcp.json --target compose asigna github y fetch a compose/mcp-stdio-bridge y docs-search a compose/mcp-remote, y conserva el entorno del servidor de GitHub tal como lo escribe la configuración: una entrada de core/referenced-secret-set cuyo valor es la referencia a variable ${GITHUB_TOKEN}, realizada por compose/dotenv-secret-set, que la escribe tal cual en el entorno del servicio, de modo que Docker Compose la rellena desde tu shell cuando se inicia el stack. Esa importación no pregunta nada y conserva el nombre del Secret en el archivo de respuestas sin usarlo.
Validar y compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

La validación imprime:
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)y la compilación, donde <workspace> representa la carpeta en la que la ejecutaste:
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 línea notice es informativa: la Feature acepta su origin de los values del Aggregate o de la infra de la Release, y el aviso informa de que una hoja está declarada en ambos. No cambia ningún veredicto.
La compilación escribe, bajo dist/helm/, un Deployment y un Service para cada uno de los dos servidores tras el puente, y un Service para docs-search. El contenedor del servidor de GitHub, en dist/helm/github-deployment.yaml, ejecuta el puente con la línea de comandos del servidor y toma su entorno del 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 no ejecuta nada: da al servidor que ejecuta otra persona un nombre dentro del clúster.
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: 443Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `import-mcp`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-mcp` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-mcp`, cuya carpeta `source` contiene lo que importa esta página. Después llama a la herramienta `import` con `workspace_root` establecido en `import-mcp/source`, `source` establecido en `.mcp.json` y `target` establecido en `helm`: lee las respuestas que necesita de `import-answers.yaml`, junto a `.mcp.json`, escribe sus borradores en `import-mcp/source` y extrae lo que necesitan. Después llama a la herramienta `validate` con `workspace_root` establecido en `import-mcp/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-mcp/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió el build; están bajo `import-mcp/source/dist/`.Ábrelo en VS Code
Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-mcp/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividad; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.
Ejecución
Nada en la compilación escribe el Secret github-mcp-token, así que créalo antes de aplicar los archivos. Escribe tu token en github-token.env, como la única línea GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, y crea el Secret a partir de él. A partir de ese momento el clúster guarda el token, así que elimina el archivo:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdAplica la compilación, como explica el paso de ejecución de Cómo se ejecuta una importación, y espera a los dos servidores:
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 metEn Docker Compose, en un espacio de trabajo importado con --target compose y construido, inicia el stack con tu token en la variable GITHUB_TOKEN de tu shell, que Docker Compose lee cuando se inicia el stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitProbarlo
El puente sirve cada servidor mediante el transporte Streamable HTTP de MCP, en /mcp en el puerto 8080. Pide al servidor fetch que abra una sesión con la solicitud initialize de MCP, que no lee ningún token.
En Docker Compose, envíala desde un contenedor desechable en la red del stack, mcp_compose, donde el nombre del servidor es 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"}}}En Kubernetes, reenvía un puerto local al Service del servidor, fetch-default, y deja el comando en ejecución:
kubectl port-forward svc/fetch-default 8080:8080Desde otra terminal, envía la misma solicitud al puerto reenviado:
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 respuesta nombra el servidor, mcp-fetch. Tarda un poco: el puente inicia la línea de comandos del servidor, uvx mcp-server-fetch, para cada sesión, y uvx primero descarga e instala los paquetes del servidor — alrededor de medio minuto en Kubernetes y alrededor de un minuto en Docker Compose en la ejecución. Las líneas : keepalive son comentarios que el flujo envía mientras tanto.
El servidor de GitHub responde a la misma solicitud en http://github:8080/mcp en Docker Compose, y a través de kubectl port-forward svc/github-default 8080:8080 en Kubernetes. initialize no lee ningún token, así que responde contenga lo que contenga el token; la ejecución usó un token de marcador:
[… 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}Detén el reenvío de puertos y después elimina lo que aplicaste y el Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenEn Docker Compose, detén y elimina el stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml down