Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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:

Terminal window
aggrega scaffold --example import-mcp

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

Terminal window
cd import-mcp

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando sua configuração MCP com três servidores: github, fetch e docs-search.

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 again

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

Terminal window
cd source

Executar a importação

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

Na saída padrão, ela lista o que gravou:

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

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

A importação executada a partir do editor: o Aggregate, a Release e o Manifest rascunhados aparecem ao lado da configuração MCP, a saída do Aggrega lista os valores mantidos como escritos e os arquivos gravados, e uma notificação informa que a importação rascunhou 3 arquivos, reconhecidos como mcp.

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 warn nomeiam 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. Em env, 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 faz aggrega pull, em release.lock, para que os rascunhos sejam validados e compilados imediatamente. Com --offline, a importação não busca nada e indica o comando aggrega pull a 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/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 — 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/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"
  • 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: npx executa um pacote npm, uvx um do PyPI.
  • O token do GitHub. O ambiente do servidor torna-se seu slot server_env. No Kubernetes, a realização de core/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 anexa core/referenced-secret em 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 Authorization permanece 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 a docs-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/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

Trê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

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

A Release rascunhada aberta no editor após a validação, com a saída do Aggrega e uma notificação sem relatar nenhum problema.

O build da Release rascunhada: uma pasta dist aparece no Explorer, a saída do Aggrega lista um Deployment e um Service para cada servidor, e uma notificação informa que 5 arquivos foram gravados.

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

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

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

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

Aplique o build, como explica a etapa de execução de Como uma importação é executada, e aguarde os dois 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

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

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

Teste

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:

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

No Kubernetes, encaminhe uma porta local para o Service do servidor, fetch-default, e deixe o comando em execução:

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

Em outro terminal, envie a mesma requisição para a porta encaminhada:

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

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

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

No Docker Compose, pare e remova a stack:

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