Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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:

Terminal window
aggrega scaffold --example import-mcp

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

Terminal window
cd import-mcp

Folder source dari contoh yang di-scaffold, dibuka di Visual Studio Code, menampilkan konfigurasi MCP-nya dengan tiga server: github, fetch, dan docs-search.

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 again

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

Terminal window
cd source

Menjalankan impor

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

Pada keluaran standar, impor mencantumkan apa yang ditulisnya:

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

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

Impor yang dijalankan dari editor: draf Aggregate, Release, dan Manifest muncul di samping konfigurasi MCP, keluaran Aggrega mencantumkan nilai yang dibawa sebagaimana tertulis dan file yang ditulis, dan sebuah notifikasi menyatakan bahwa impor menyusun draf 3 file, dikenali sebagai mcp.

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 warn menyebutkan 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. Pada env, nilai ${GITHUB_TOKEN} hanyalah sebuah referensi variabel, sehingga tidak memuat nilai sendiri dan tidak ada peringatan yang menyebutkannya.
  • Baris Pull complete adalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukan aggrega pull, ke dalam release.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan --offline, impor tidak mengambil apa pun dan menyebutkan perintah aggrega pull yang 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/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 — bagaimana setiap server dijalankan atau dijangkau, sebagaimana dinyatakan konfigurasi, dan Secret tempat token server GitHub dibaca:

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"
  • Lingkungan, development, adalah nilai default yang ditulis impor karena tidak ada konfigurasi yang menyebutkannya; ubah jika Release di-deploy di tempat lain.
  • stdio_runtime dibaca dari setiap perintah: npx menjalankan paket npm, uvx paket PyPI.
  • Token GitHub. Lingkungan server menjadi slot server_env-nya. Di Kubernetes, realisasi core/referenced-secret-set, yaitu helm/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 helm impor melampirkan core/referenced-secret sebagai 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 Authorization tetap 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 ke docs-search, header tersebut ditempatkan pada koneksi itu.

manifest.yaml — satu realisasi per server, berdasarkan namanya, dan realisasi 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

Tiga 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

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

Draf Release yang dibuka di editor setelah divalidasi, dengan keluaran Aggrega dan sebuah notifikasi yang sama-sama melaporkan tidak ada masalah.

Build dari draf Release: folder dist muncul di Explorer, keluaran Aggrega mencantumkan sebuah Deployment dan sebuah Service untuk setiap server, dan sebuah notifikasi menyatakan bahwa 5 file telah ditulis.

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

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

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

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

Terapkan build, seperti yang dijelaskan langkah eksekusi di Cara impor berjalan, dan tunggu kedua server:

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

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

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

Mengujinya

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:

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

Di Kubernetes, teruskan sebuah port lokal ke Service server, fetch-default, dan biarkan perintahnya tetap berjalan:

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

Dari terminal lain, kirim permintaan yang sama ke port yang diteruskan:

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

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

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

Di Docker Compose, hentikan dan hapus stack:

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