Importar uma configuração de cliente MCP
Este guia prático importa os servidores Model Context Protocol com que um assistente de programação está configurado — dois que inicia a partir de uma linha de comandos e um que outra pessoa executa — e compila os servidores para Kubernetes, para que um agente em execução num cluster possa chegar às mesmas ferramentas. A importação gera como rascunho cada ficheiro que o build lê: a linha de comandos ou o endereço de cada servidor, a realização que o executa e a proveniência do token do servidor GitHub. Cada ficheiro e cada bloco de saída abaixo provém de uma execução real; a configuração e cada etapa do guia estão no exemplo import-mcp, onde um script de verificação executa novamente a importação, compara o que ela escreve, o que imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.
Gerar o exemplo
É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example import-mcpDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, que contém o que esta página importa e é onde a importação é executada:
cd import-mcp
A configuração
O .mcp.json do Claude Code, na raiz de um projeto:
{ "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}" } } }}A importação lê da mesma forma o claude_desktop_config.json do Claude Desktop, o .cursor/mcp.json do Cursor, o .vscode/mcp.json do Visual Studio Code e um server.json de um registo MCP. Ao lado da configuração, um .aggrega-config.yaml faz da pasta uma área de trabalho:
# 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 rascunha um Manifest a partir das Recipes do catálogo. O espaço de trabalho não indica nenhuma pasta de catálogo, pelo que a importação lê o catálogo da biblioteca padrão a partir do registry de onde obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que o registo que a importação escreve junto aos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indique as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa antes com base nessas pastas.
O ficheiro de respostas
No Kubernetes, o servidor do GitHub lê o seu token de um Secret mantido pelo cluster, e nenhuma configuração MCP indica esse Secret: a configuração lê o token da variável GITHUB_TOKEN da shell. Por isso, a importação pergunta o nome do Secret. O exemplo guarda a resposta em import-answers.yaml, junto a .mcp.json, onde a importação a procura:
# 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"A própria importação escreveu o ficheiro, da primeira vez que foi executada sem resposta: sem um terminal onde perguntar, rascunhou todo o resto, deixou vazio o nome do Secret, listou a chave no ficheiro e parou com
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 againNum terminal, faz antes a pergunta e escreve a resposta no ficheiro para a importação seguinte. A resposta é o nome do Secret, github-mcp-token, nunca o token. O ficheiro de respostas da importação descreve o ficheiro e as perguntas na íntegra.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que indica um ficheiro de respostas guardado noutro local.
Entre em source:
cd sourceExecutar a importação
aggrega import .mcp.json --target helmNa saída padrão, lista o que escreveu:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> a representar a pasta em que a executou:
[… 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 é uma instância da ferramenta MCP da biblioteca padrão, core/ai-tool/mcp, pelo que a importação não pondera nenhum candidato e não imprime nenhuma linha mapped.
- As linhas
warnindicam os valores que a configuração de um servidor contém. Nenhum cliente MCP marca qualquer um deles como credencial, e qualquer um deles pode transportar uma — uma chave num argumento da linha de comandos, um token num endereço —, pelo que a importação indica cada item de uma linha de comandos, cada cabeçalho e cada endereço que a configuração transportava, pelo respetivo servidor e posição, nunca pelo valor. Leia-os antes de partilhar o rascunho. Emenv, o valor${GITHUB_TOKEN}é uma referência a uma variável e nada mais, pelo que não contém valor próprio e nenhum aviso o indica. - A linha
Pull completeé a importação a obter aquilo de que a Release rascunhada depende, como fazaggrega pull, pararelease.lock, para que os rascunhos sejam validados e compilados de imediato. Com--offline, a importação não obtém nada e indica o comandoaggrega pulla executar.
O que a importação escreve
O Aggregate, a Release e o Manifest chamam-se imported/mcp, a partir do ficheiro, .mcp.json, uma vez que a configuração de um cliente não tem nome próprio — o server.json de um registo recebe o nome do seu name — no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definições).
aggregate.yaml — uma instância por servidor, e ainda nada que as utilize:
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 — como cada servidor é executado ou alcançado, tal como a configuração o indica, e o Secret a partir do qual é lido o token do servidor 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"- O ambiente,
development, é um valor predefinido que a importação escreve porque nenhuma configuração indica um; altere-o se a Release for implementada noutro lugar. stdio_runtimeé deduzido de cada comando:npxexecuta um pacote npm,uvxum do PyPI.- O token do GitHub. O ambiente do servidor passa a ser o seu slot
server_env. No Kubernetes, a realização decore/referenced-secret-set,helm/k8s-secret-set, escreve os valores que recebe num Secret que o build renderiza, o que colocaria o token num ficheiro. Por isso, para--target helm, a importação anexa antescore/referenced-secret, que indica um Secret que o cluster já contém — a resposta,github-mcp-token— com uma chave de dados por variável,GITHUB_PERSONAL_ACCESS_TOKEN. A ponte importa cada chave de dados desse Secret como uma variável com o mesmo nome, pelo que o servidor lê o seu token tal como fazia na sua máquina, e nenhum ficheiro renderizado o transporta. - O cabeçalho
Authorizationmantém-se como comentário. A credencial de um servidor remoto é detida por quem o chama, na própria ligação desse chamador à ferramenta, e esta área de trabalho ainda não tem nenhum chamador. Quando ligar um agente adocs-search, o cabeçalho fica nessa ligação.
manifest.yaml — uma realização por servidor, pelo respetivo nome, e a realização do 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-secretTrês Recipes do Kubernetes realizam core/ai-tool/mcp — uma para um servidor publicado como imagem, uma para um pacote executado atrás de uma ponte, uma para um servidor que outra pessoa executa — e qual delas se adequa é uma propriedade de cada servidor, que a configuração indica. Por isso, a importação mapeia cada instância pelo respetivo nome: github e fetch, iniciados a partir de uma linha de comandos, são executados atrás da ponte stdio, helm/mcp-stdio-bridge; docs-search, que outra pessoa executa, é mapeado para helm/mcp-remote, que não executa nada e publica o endereço. O Secret do token é mapeado para helm/k8s-existing-secret, que referencia um Secret em vez de escrever um.
release.lock regista, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registo do que a importação escreveu, que um aggrega import --sync posterior lê.
No Docker Compose
Os servidores também são executados no Docker Compose. aggrega import .mcp.json --target compose mapeia github e fetch para compose/mcp-stdio-bridge e docs-search para compose/mcp-remote, e mantém o ambiente do servidor GitHub tal como a configuração o escreve: uma entrada de core/referenced-secret-set cujo valor é a referência de variável ${GITHUB_TOKEN}, realizada por compose/dotenv-secret-set, que a escreve tal como está no ambiente do serviço, de modo que o Docker Compose a preenche a partir da sua shell quando a stack arranca. Essa importação não pede nada e mantém o nome do Secret no ficheiro de respostas sem o utilizar.
Validar e compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

A validação 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)e o build, com <workspace> a representar a pasta onde o executou:
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>/distA linha notice é consultiva: a Feature aceita o seu origin a partir de values do Aggregate ou de infra da Release, e o aviso indica que uma folha está declarada em ambos. Não altera nenhum veredicto.
O build escreve, em dist/helm/, um Deployment e um Service para cada um dos dois servidores com ponte, e um Service para docs-search. O contentor do servidor GitHub, em dist/helm/github-deployment.yaml, executa a ponte com a linha de comandos do servidor e obtém o seu ambiente a partir do 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ão executa nada: atribui ao servidor que outra pessoa executa um nome dentro do 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: 443Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole nele este prompt.
Usa apenas as ferramentas do Aggrega e não cries nenhuma pasta. Se a pasta do espaço de trabalho ainda não contiver uma pasta `import-mcp`, chama uma vez a ferramenta `scaffold` com `example` definido como `import-mcp` e sem `dir`: escreve o exemplo numa nova pasta `import-mcp`, cuja pasta `source` contém o que esta página importa. Em seguida, chama a ferramenta `import` com `workspace_root` definido como `import-mcp/source`, `source` definido como `.mcp.json` e `target` definido como `helm`: lê as respostas de que precisa em `import-answers.yaml`, ao lado de `.mcp.json`, escreve os seus rascunhos em `import-mcp/source` e obtém aquilo de que precisam. Em seguida, chama a ferramenta `validate` com `workspace_root` definido como `import-mcp/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-mcp/source`, `release` definido como `release.yaml` e `write` definido como true. Diz-me que ficheiros o build escreveu; estão em `import-mcp/source/dist/`.Abrir no VS Code
Com a extensão do Aggrega para o Visual Studio Code instalada, abra no VS Code a pasta import-mcp/source, onde a importação escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as ligações entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um é também um botão no painel Commands da vista Aggrega na barra de atividades; Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code cobre o resto.
Execução
Nada no build escreve o Secret github-mcp-token, pelo que deve criá-lo antes de aplicar os ficheiros. Escreva o token em github-token.env, como a única linha GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, e crie o Secret a partir dele. O cluster passa então a guardar o token, por isso elimine o ficheiro:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdAplique o build, como explica o passo de execução de Como decorre uma importação, e aguarde pelos dois 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 metNo Docker Compose, num espaço de trabalho importado com --target compose e construído, inicie a stack com o seu token na variável GITHUB_TOKEN da shell, que o Docker Compose lê quando a stack arranca:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitTestar
A ponte serve cada servidor através do transporte Streamable HTTP do MCP, em /mcp na porta 8080. Peça ao servidor fetch que abra uma sessão com o pedido initialize do MCP, que não lê nenhum token.
No Docker Compose, envie-o a partir de um contentor descartável na rede da stack, mcp_compose, onde o nome do servidor é 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"}}}No Kubernetes, reencaminhe uma porta local para o Service do servidor, fetch-default, e deixe o comando em execução:
kubectl port-forward svc/fetch-default 8080:8080Noutro terminal, envie o mesmo pedido para a porta reencaminhada:
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"}}}A resposta nomeia o servidor, mcp-fetch. Demora algum tempo: a ponte inicia a linha de comandos do servidor, uvx mcp-server-fetch, para cada sessão, e o uvx transfere e instala primeiro os pacotes do servidor — cerca de meio minuto no Kubernetes e cerca de um minuto no Docker Compose na execução. As linhas : keepalive são comentários que o stream envia entretanto.
O servidor do GitHub responde ao mesmo pedido em http://github:8080/mcp no Docker Compose, e através de kubectl port-forward svc/github-default 8080:8080 no Kubernetes. initialize não lê nenhum token, pelo que responde seja qual for o conteúdo do token; a execução usou um token provisório:
[… 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}Pare o reencaminhamento de porta e, em seguida, remova o que aplicou e o Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenNo Docker Compose, pare e remova a stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml down