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

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:

Terminal window
aggrega scaffold --example import-mcp

Depois, 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:

Terminal window
cd import-mcp

A pasta source do exemplo gerado aberta no Visual Studio Code, a mostrar a 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 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 again

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

Terminal window
cd source

Executar a importação

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

Na saída padrão, lista o que escreveu:

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

Na 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 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 em rascunho aparecem ao lado da configuração MCP, a saída do Aggrega lista os valores mantidos tal como escritos e os ficheiros escritos, e uma notificação indica que a importação gerou 3 ficheiros em rascunho, reconhecidos como mcp.

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 warn indicam 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. Em env, 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 faz aggrega pull, para release.lock, para que os rascunhos sejam validados e compilados de imediato. Com --offline, a importação não obtém nada e indica o comando aggrega pull a 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/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 o indica, e o Secret a partir do qual é lido o token do servidor 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"
  • 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: npx executa um pacote npm, uvx um do PyPI.
  • O token do GitHub. O ambiente do servidor passa a ser o seu slot server_env. No Kubernetes, a realização de core/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 antes core/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 Authorization manté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 a docs-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/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 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

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

A Release em rascunho aberta no editor após a validação, com a saída do Aggrega e uma notificação a não reportarem nenhum problema.

O build da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista um Deployment e um Service para cada servidor, e uma notificação indica que foram escritos 5 ficheiros.

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

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

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 o passo de execução de Como decorre uma importação, e aguarde pelos 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, 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:

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

Testar

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:

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, reencaminhe 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

Noutro terminal, envie o mesmo pedido para a porta reencaminhada:

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

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