Mengimpor konfigurasi klien MCP
Panduan langkah demi langkah ini mengimpor server Model Context Protocol yang dikonfigurasi pada sebuah asisten pemrograman — dua yang dijalankannya dari baris perintah dan satu yang dijalankan pihak lain — dan membangun server-server tersebut untuk Kubernetes, sehingga agen yang berjalan di kluster dapat menjangkau alat yang sama. Impor menyusun draf setiap file yang dibaca build: baris perintah atau alamat setiap server, realisasi yang menjalankannya, dan asal token server GitHub. Setiap file dan setiap blok keluaran di bawah ini berasal dari eksekusi nyata; konfigurasi dan setiap tahap panduan ini ada di contoh import-mcp, tempat sebuah skrip pemeriksaan menjalankan impor lagi, membandingkan apa yang ditulisnya, apa yang dicetaknya, dan blok-blok yang dikutip halaman ini dengan file yang disimpan di sana, serta memvalidasi dan membangun apa yang ditulis impor.
Membuat contoh
Anda dapat menjalankan impor ini dengan perintah di halaman ini, atau meminta asisten AI Anda menjalankannya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example import-mcpKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru; perintah sesudahnya, di bawah, berpindah ke folder source milik folder baru itu, yang berisi apa yang diimpor halaman ini dan merupakan tempat impor dijalankan:
cd import-mcp
Konfigurasi
.mcp.json milik Claude Code, di direktori root sebuah proyek:
{ "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}" } } }}Impor membaca claude_desktop_config.json milik Claude Desktop, .cursor/mcp.json milik Cursor, .vscode/mcp.json milik Visual Studio Code, dan server.json dari registri MCP dengan cara yang sama. Di samping konfigurasi, sebuah .aggrega-config.yaml menjadikan folder tersebut sebuah ruang kerja:
# 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 menyusun draf Manifest dari Recipes katalog. Ruang kerja tidak menyebutkan folder katalog apa pun, jadi impor membaca katalog pustaka standar dari registry tempat impor mengambil importer-nya: snapshot bertanda tangan dari katalog yang diterbitkan, yang diambil, diverifikasi, dan disimpan di cache konten ruang kerja oleh impor pertama, serta disebutkan melalui digest-nya dalam catatan yang ditulis impor di samping draf-drafnya. Ruang kerja yang menyebutkan folder katalognya sendiri — di AGGREGA_CATALOG_DIRS, atau di bawah workspace.catalog_dirs — mengimpor terhadap folder-folder itu sebagai gantinya.
Berkas jawaban
Di Kubernetes, server GitHub membaca token-nya dari sebuah Secret yang disimpan klaster, dan tidak ada konfigurasi MCP yang menyebutkan Secret tersebut: konfigurasi membaca token dari GITHUB_TOKEN di shell Anda. Karena itu, impor menanyakan nama Secret tersebut. Contoh ini menyimpan jawabannya di import-answers.yaml, di samping .mcp.json, tempat impor mencarinya:
# 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"Impor menulis file itu sendiri, saat pertama kali dijalankan tanpa jawaban: tanpa terminal untuk bertanya, impor menyusun draf semua hal lainnya, membiarkan nama Secret kosong, mencantumkan kuncinya di file, lalu berhenti dengan
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 againDi terminal, impor justru mengajukan pertanyaannya, lalu menulis jawabannya ke file untuk impor berikutnya. Jawabannya adalah nama Secret, github-mcp-token, bukan token-nya. File jawaban impor menjelaskan file dan pertanyaannya secara lengkap.
aggrega import mencantumkan setiap flag yang diterima perintah ini, termasuk --answers, yang menyebutkan file jawaban yang disimpan di tempat lain.
Pindah ke source:
cd sourceMenjalankan impor
aggrega import .mcp.json --target helmPada keluaran standar, impor mencantumkan apa yang ditulisnya:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonPada galat standar, dengan <workspace> mewakili folder tempat Anda menjalankannya:
[… 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)
Setiap server adalah instans dari alat MCP milik pustaka standar, core/ai-tool/mcp, sehingga impor tidak menimbang kandidat apa pun dan tidak mencetak baris mapped apa pun.
- Baris
warnmenyebutkan nilai-nilai yang dimuat konfigurasi sebuah server. Tidak ada klien MCP yang menandai satu pun dari nilai tersebut sebagai kredensial, dan masing-masing dapat membawa kredensial — sebuah kunci dalam argumen baris perintah, sebuah token dalam alamat — sehingga impor menyebutkan setiap item baris perintah, setiap header, dan setiap alamat yang dibawa konfigurasi berdasarkan server dan posisinya, tidak pernah berdasarkan nilainya. Bacalah semuanya sebelum Anda membagikan draf. Padaenv, nilai${GITHUB_TOKEN}hanyalah sebuah referensi variabel, sehingga tidak memuat nilai sendiri dan tidak ada peringatan yang menyebutkannya. - Baris
Pull completeadalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukanaggrega pull, ke dalamrelease.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan--offline, impor tidak mengambil apa pun dan menyebutkan perintahaggrega pullyang perlu dijalankan.
Apa yang ditulisnya
Aggregate, Release, dan Manifest diberi nama imported/mcp, berdasarkan file, .mcp.json, karena konfigurasi klien tidak membawa nama sendiri — server.json milik registri dinamai berdasarkan name miliknya — di bawah namespace yang ditetapkan oleh pengaturan target_namespace milik pengimpor, yaitu imported kecuali Anda menetapkan yang lain (Pengaturan).
aggregate.yaml — satu instans per server, dan belum ada yang menggunakannya:
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 — bagaimana setiap server dijalankan atau dijangkau, sebagaimana dinyatakan konfigurasi, dan Secret tempat token server GitHub dibaca:
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"- Lingkungan,
development, adalah nilai default yang ditulis impor karena tidak ada konfigurasi yang menyebutkannya; ubah jika Release di-deploy di tempat lain. stdio_runtimedibaca dari setiap perintah:npxmenjalankan paket npm,uvxpaket PyPI.- Token GitHub. Lingkungan server menjadi slot
server_env-nya. Di Kubernetes, realisasicore/referenced-secret-set, yaituhelm/k8s-secret-set, menulis nilai-nilai yang diberikan kepadanya ke dalam Secret yang dirender oleh build, yang akan menempatkan token di dalam sebuah file. Karena itu, untuk--target helmimpor melampirkancore/referenced-secretsebagai gantinya, dengan menyebutkan Secret yang sudah dimiliki kluster — jawabannya,github-mcp-token— dengan satu kunci data per variabel,GITHUB_PERSONAL_ACCESS_TOKEN. Bridge mengimpor setiap kunci data dari Secret tersebut sebagai variabel dengan nama yang sama, sehingga server membaca tokennya seperti di mesin Anda, dan tidak ada file hasil render yang memuatnya. - Header
Authorizationtetap menjadi komentar. Kredensial server jarak jauh dipegang oleh siapa pun yang memanggilnya, pada koneksi milik pemanggil itu sendiri ke alat tersebut, dan ruang kerja ini belum memiliki pemanggil. Saat Anda menghubungkan sebuah agen kedocs-search, header tersebut ditempatkan pada koneksi itu.
manifest.yaml — satu realisasi per server, berdasarkan namanya, dan realisasi 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-secretTiga Recipes Kubernetes merealisasikan core/ai-tool/mcp — satu untuk server yang diterbitkan sebagai image, satu untuk paket yang dijalankan di balik bridge, satu untuk server yang dijalankan pihak lain — dan mana yang cocok adalah properti setiap server, yang dinyatakan konfigurasi. Karena itu impor memetakan setiap instans berdasarkan namanya: github dan fetch, yang dijalankan dari baris perintah, berjalan di balik bridge stdio, helm/mcp-stdio-bridge; docs-search, yang dijalankan pihak lain, dipetakan ke helm/mcp-remote, yang tidak menjalankan apa pun dan menerbitkan alamatnya. Secret milik token dipetakan ke helm/k8s-existing-secret, yang mereferensikan sebuah Secret alih-alih menulisnya.
release.lock mencatat entitas katalog tempat Release diselesaikan, berdasarkan digest, dan .aggrega-import.json adalah catatan tentang apa yang ditulis impor, yang dibaca oleh aggrega import --sync berikutnya.
Pada Docker Compose
Server-server tersebut juga berjalan di Docker Compose. aggrega import .mcp.json --target compose memetakan github dan fetch ke compose/mcp-stdio-bridge dan docs-search ke compose/mcp-remote, serta mempertahankan lingkungan server GitHub sebagaimana ditulis konfigurasi: sebuah entri core/referenced-secret-set yang nilainya adalah referensi variabel ${GITHUB_TOKEN}, direalisasikan oleh compose/dotenv-secret-set, yang menuliskannya ke lingkungan layanan sebagaimana tertulis, sehingga Docker Compose mengisinya dari shell Anda saat stack dimulai. Impor itu tidak menanyakan apa pun, dan menyimpan nama Secret di file jawaban tanpa menggunakannya.
Validasi dan build
aggrega validate --release release.yamlaggrega build --release release.yaml

Validasi mencetak:
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)dan build, dengan <workspace> mewakili folder tempat Anda menjalankannya:
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>/distBaris notice bersifat anjuran: Feature menerima origin-nya dari values milik Aggregate atau infra milik Release, dan pemberitahuan tersebut melaporkan bahwa satu leaf dideklarasikan di keduanya. Baris ini tidak mengubah putusan apa pun.
Build menulis, di bawah dist/helm/, sebuah Deployment dan sebuah Service untuk masing-masing dari dua server yang dijembatani, serta satu Service untuk docs-search. Container server GitHub, di dist/helm/github-deployment.yaml, menjalankan bridge dengan baris perintah server, dan mengambil lingkungannya dari 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 tidak menjalankan apa pun: file ini memberi server yang dijalankan pihak lain sebuah nama di dalam kluster.
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: 443Dengan asisten AI
Asisten AI yang disiapkan dengan alat-alat Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke dalamnya.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder Workspace belum berisi folder `import-mcp`, panggil alat `scaffold` sekali dengan `example` diatur ke `import-mcp` dan tanpa `dir`: alat itu menulis contoh ke folder `import-mcp` baru, yang folder `source`-nya berisi apa yang diimpor halaman ini. Lalu panggil alat `import` dengan `workspace_root` diatur ke `import-mcp/source`, `source` diatur ke `.mcp.json`, dan `target` diatur ke `helm`: alat itu membaca jawaban yang dibutuhkannya dari `import-answers.yaml` di samping `.mcp.json`, menulis drafnya ke `import-mcp/source`, dan menarik apa yang dibutuhkan draf tersebut. Lalu panggil alat `validate` dengan `workspace_root` diatur ke `import-mcp/source` dan `release` diatur ke `release.yaml`, serta alat `build` dengan `workspace_root` diatur ke `import-mcp/source`, `release` diatur ke `release.yaml`, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis build; file-file itu ada di bawah `import-mcp/source/dist/`.Membukanya di VS Code
Dengan ekstensi Aggrega untuk Visual Studio Code terpasang, buka folder import-mcp/source di VS Code, tempat impor menulis drafnya. Folder ini berisi satu Release, yaitu draf release.yaml, sehingga editor memilihnya untuk Anda, dan editor memeriksa draf terhadap Release itu saat Anda menyuntingnya, menandai temuannya di file dan di panel Problems. Aggrega: Show topology graph, di Command Palette, menggambar komponen Release dan koneksi di antaranya. Aggrega: Build, Aggrega: Preview build, dan Aggrega: Pull bekerja pada Release yang sama, dan masing-masing juga merupakan tombol di panel Commands pada tampilan Aggrega di activity bar; Build menulis file-filenya ke dist/ di folder tersebut. Menggunakan Aggrega di Visual Studio Code membahas sisanya.
Menjalankannya
Tidak ada bagian dari build yang menulis Secret github-mcp-token, jadi buatlah sebelum Anda menerapkan berkas-berkasnya. Tulis token Anda ke github-token.env, sebagai satu baris GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, lalu buat Secret dari berkas itu. Setelah itu klaster menyimpan token tersebut, jadi hapus berkasnya:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdTerapkan build, seperti yang dijelaskan langkah eksekusi di Cara impor berjalan, dan tunggu kedua server:
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 metDi Docker Compose, dalam workspace yang diimpor dengan --target compose dan sudah di-build, jalankan stack dengan token Anda di GITHUB_TOKEN pada shell Anda, yang dibaca Docker Compose saat stack dimulai:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitMengujinya
Bridge melayani setiap server melalui transport Streamable HTTP milik MCP, di /mcp pada port 8080. Minta server fetch membuka sesi dengan permintaan initialize milik MCP, yang tidak membaca token apa pun.
Di Docker Compose, kirimkan dari kontainer sekali pakai di jaringan stack, mcp_compose, tempat nama server adalah 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"}}}Di Kubernetes, teruskan sebuah port lokal ke Service server, fetch-default, dan biarkan perintahnya tetap berjalan:
kubectl port-forward svc/fetch-default 8080:8080Dari terminal lain, kirim permintaan yang sama ke port yang diteruskan:
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"}}}Balasan menyebutkan nama server, mcp-fetch. Ini memerlukan waktu: bridge memulai baris perintah server, uvx mcp-server-fetch, untuk setiap sesi, dan uvx terlebih dahulu mengunduh dan memasang paket-paket server — sekitar setengah menit di Kubernetes dan sekitar satu menit di Docker Compose dalam eksekusi tersebut. Baris : keepalive adalah komentar yang dikirim stream sementara itu.
Server GitHub menjawab permintaan yang sama di http://github:8080/mcp pada Docker Compose, dan melalui kubectl port-forward svc/github-default 8080:8080 pada Kubernetes. initialize tidak membaca token apa pun, sehingga server menjawab apa pun isi token tersebut; eksekusi tersebut menggunakan token pengganti:
[… 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}Hentikan penerusan port, lalu hapus apa yang Anda terapkan beserta Secret tersebut:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenDi Docker Compose, hentikan dan hapus stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml down