Importar uma configuração de cliente MCP
Este passo a passo importa os servidores Model Context Protocol com que um assistente de programação está configurado — dois que ele inicia a partir de uma linha de comando e um que outra pessoa executa — e compila os servidores para Kubernetes, para que um agente em execução em um cluster possa alcançar as mesmas ferramentas. A importação gera como rascunho cada arquivo que o build lê: a linha de comando ou o endereço de cada servidor, a realização que o executa e de onde vem o token do servidor GitHub. Cada arquivo e cada bloco de saída abaixo vem de uma execução real; a configuração e cada etapa do passo a passo estão no exemplo import-mcp, onde um script de verificação executa a importação novamente, compara o que ela escreve, o que ela imprime e os blocos que esta página cita com os arquivos mantidos ali, e valida e compila o que a importação escreveu.
Gerar o exemplo
Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example import-mcpEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, 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 maneira 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 registro MCP. Ao lado da configuração, um .aggrega-config.yaml torna a pasta um workspace:
# 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, então a importação lê o catálogo da biblioteca padrão a partir do registro do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que o histórico que a importação escreve ao lado dos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indica suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa a partir delas em vez disso.
O arquivo de respostas
No Kubernetes, o servidor do GitHub lê o seu token de um Secret mantido pelo cluster, e nenhuma configuração MCP nomeia esse Secret: a configuração lê o token da variável GITHUB_TOKEN do seu shell. Por isso a importação pergunta o nome do Secret. O exemplo guarda a resposta em import-answers.yaml, ao lado de .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 arquivo, na primeira vez em que foi executada sem resposta: sem um terminal onde perguntar, rascunhou todo o resto, deixou vazio o nome do Secret, listou a chave no arquivo 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 againEm um terminal, ela faz a pergunta em vez disso e escreve a resposta no arquivo para a próxima importação. A resposta é o nome do Secret, github-mcp-token, nunca o token. O arquivo de respostas da importação descreve o arquivo e as perguntas por completo.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que nomeia um arquivo de respostas mantido em outro lugar.
Entre em source:
cd sourceExecutar a importação
aggrega import .mcp.json --target helmNa saída padrão, ela lista o que gravou:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> representando a pasta em que você 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, então a importação não pondera nenhum candidato e não imprime nenhuma linha mapped.
- As linhas
warnnomeiam 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 carregar uma — uma chave em um argumento de linha de comando, um token em um endereço —, então a importação nomeia cada item de uma linha de comando, cada cabeçalho e cada endereço que a configuração carregava, pelo seu servidor e pela sua posição, nunca pelo seu valor. Leia-os antes de compartilhar o rascunho. Emenv, o valor${GITHUB_TOKEN}é uma referência a variável e nada mais, então não contém valor próprio e nenhum aviso o nomeia. - A linha
Pull completeé a importação buscando aquilo de que a Release rascunhada depende, como fazaggrega pull, emrelease.lock, para que os rascunhos sejam validados e compilados imediatamente. Com--offline, a importação não busca nada e indica o comandoaggrega pulla executar.
O que a importação grava
O Aggregate, a Release e o Manifest se chamam imported/mcp, a partir do arquivo, .mcp.json, já que a configuração de um cliente não carrega nome próprio — o server.json de um registro recebe o nome do seu name — sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).
aggregate.yaml — uma instância por servidor, e nada que as use ainda:
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 declara, e o Secret do qual o token do servidor GitHub é lido:
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 padrão que a importação escreve porque nenhuma configuração nomeia um; altere-o se a Release for implantada em outro lugar. stdio_runtimeé deduzido de cada comando:npxexecuta um pacote npm,uvxum do PyPI.- O token do GitHub. O ambiente do servidor torna-se seu slot
server_env. No Kubernetes, a realização decore/referenced-secret-set,helm/k8s-secret-set, escreve os valores que recebe em um Secret que o build renderiza, o que colocaria o token em um arquivo. Por isso, para--target helm, a importação anexacore/referenced-secretem vez disso, nomeando 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 de mesmo nome, então o servidor lê seu token como fazia na sua máquina, e nenhum arquivo renderizado o carrega. - O cabeçalho
Authorizationpermanece um comentário. A credencial de um servidor remoto é mantida por quem o chama, na própria conexão desse chamador com a ferramenta, e este workspace ainda não tem nenhum chamador. Quando você conectar um agente adocs-search, o cabeçalho vai nessa conexão.
manifest.yaml — uma realização por servidor, pelo seu 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 aplica é uma propriedade de cada servidor, que a configuração declara. Por isso, a importação mapeia cada instância pelo seu nome: github e fetch, iniciados a partir de uma linha de comando, 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 registra, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registro do que a importação gravou, 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 grava tal como está escrita no ambiente do serviço, de modo que o Docker Compose a preenche a partir do seu shell quando a stack é iniciada. Essa importação não pergunta nada e mantém o nome do Secret no arquivo de respostas sem usá-lo.
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> representando a pasta em que você 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 seu origin a partir de values do Aggregate ou de infra da Release, e o aviso informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.
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 contêiner do servidor GitHub, em dist/helm/github-deployment.yaml, executa a ponte com a linha de comando do servidor e obtém seu ambiente 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: dá 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 este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do workspace ainda não contiver uma pasta `import-mcp`, chame a ferramenta `scaffold` uma vez com `example` definido como `import-mcp` e sem `dir`: ela grava o exemplo em uma nova pasta `import-mcp`, cuja pasta `source` contém o que esta página importa. Em seguida, chame a ferramenta `import` com `workspace_root` definido como `import-mcp/source`, `source` definido como `.mcp.json` e `target` definido como `helm`: ela lê as respostas de que precisa em `import-answers.yaml`, ao lado de `.mcp.json`, grava seus rascunhos em `import-mcp/source` e faz pull do que eles precisam. Em seguida, chame 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. Diga-me quais arquivos o build gravou; eles ficam em `import-mcp/source/dist/`.Abra no VS Code
Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code a pasta import-mcp/source, onde a importação gravou seus rascunhos. A pasta contém uma única Release, o release.yaml rascunhado, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as conexõ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 visualização Aggrega na barra de atividades; Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.
Execução
Nada no build escreve o Secret github-mcp-token, então crie-o antes de aplicar os arquivos. Escreva seu token em github-token.env, como a única linha GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, e crie o Secret a partir dele. A partir daí o cluster guarda o token, então exclua o arquivo:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdAplique o build, como explica a etapa de execução de Como uma importação é executada, e aguarde os 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, em um workspace importado com --target compose e construído, inicie a stack com seu token na variável GITHUB_TOKEN do seu shell, que o Docker Compose lê quando a stack inicia:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitTeste
A ponte serve cada servidor pelo transporte Streamable HTTP do MCP, em /mcp na porta 8080. Peça ao servidor fetch que abra uma sessão com a requisição initialize do MCP, que não lê nenhum token.
No Docker Compose, envie-a a partir de um contêiner 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, encaminhe uma porta local para o Service do servidor, fetch-default, e deixe o comando em execução:
kubectl port-forward svc/fetch-default 8080:8080Em outro terminal, envie a mesma requisição para a porta encaminhada:
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. Ela demora um pouco: a ponte inicia a linha de comando do servidor, uvx mcp-server-fetch, para cada sessão, e uvx primeiro baixa e instala 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 nesse meio-tempo.
O servidor do GitHub responde à mesma requisição em http://github:8080/mcp no Docker Compose, e por meio de kubectl port-forward svc/github-default 8080:8080 no Kubernetes. initialize não lê nenhum token, então 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}Interrompa o encaminhamento de porta e, em seguida, remova o que você 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