Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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:

Terminal window
aggrega scaffold --example import-mcp

Despué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:

Terminal window
cd import-mcp

La carpeta source del ejemplo generado abierta en Visual Studio Code, que muestra su configuración MCP con tres servidores: github, fetch y docs-search.

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 again

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

Terminal window
cd source

Ejecutar la importación

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

En la salida estándar enumera lo que escribió:

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

En 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 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)

La importación ejecutada desde el editor: el Aggregate, la Release y el Manifest en borrador aparecen junto a la configuración MCP, la salida de Aggrega enumera los valores conservados tal como están escritos y los archivos escritos, y una notificación indica que la importación generó 3 archivos en borrador, reconocidos como mcp.

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 warn nombran 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} de env es 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 complete es la importación obteniendo aquello de lo que depende la Release redactada, como hace aggrega pull, en release.lock, para que los borradores se validen y se compilen de inmediato. Con --offline, la importación no obtiene nada e indica el comando aggrega pull que 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/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 — 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/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"
  • 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_runtime se deduce de cada comando: npx ejecuta un paquete npm, uvx uno de PyPI.
  • El token de GitHub. El entorno del servidor se convierte en su ranura server_env. En Kubernetes, la realización de core/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 helm la importación adjunta en su lugar core/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 Authorization sigue 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 a docs-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/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

Tres 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

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

La Release en borrador abierta en el editor tras validarla, con la salida de Aggrega y una notificación que no informan de ningún problema.

El build de la Release en borrador: aparece una carpeta dist en el Explorador, la salida de Aggrega enumera un Deployment y un Service para cada servidor, y una notificación indica que se escribieron 5 archivos.

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

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

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

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

Aplica la compilación, como explica el paso de ejecución de Cómo se ejecuta una importación, y espera a los dos servidores:

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

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

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

Probarlo

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:

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"}}}

En Kubernetes, reenvía un puerto local al Service del servidor, fetch-default, y deja el comando en ejecución:

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

Desde otra terminal, envía la misma solicitud al puerto reenviado:

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

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

En Docker Compose, detén y elimina el stack:

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