Alamat tool dari sebuah Secret — server Model Context Protocol yang membaca kuncinya dari alamatnya
Beberapa server Model Context Protocol yang dijalankan pihak lain membaca kuncinya dari
alamatnya sendiri — https://mcp.example.com/mcp?api_key=<key> — alih-alih
dari header permintaan. Alamat seperti itu tidak dapat dituliskan ke dalam tool seperti
alamat biasa: tool menerbitkan alamatnya sebagaimana tertulis, sehingga kunci tersebut akan
sampai ke setiap berkas yang dicapai alamat itu.
Workspace ini menyimpan alamat dalam dua bagian. Tool, core/ai-tool/mcp,
menyimpan alamat tanpa bagian yang membawa kunci. Koneksi agen
ke tool menyimpan seluruh alamat sebagai rahasia, dan Release menyebutkan tempat
rahasia itu berada. Workspace ini dibangun untuk Kubernetes dan untuk Docker Compose, dan pada keduanya tidak ada
berkas hasil render yang membawa kunci.
Agen dideklarasikan dalam katalog milik workspace ini sendiri, sehingga socket yang menyimpan alamat dituliskan di sini secara lengkap. Runtime agen pustaka standar core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk dan mastra, serta platform core/ai-agent/flowise dan n8n, mendeklarasikan socket tools dengan dua slot yang sama. Tool, kedua Features kredensial, dan realisasinya disertakan dalam katalog pustaka standar.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
search | core/ai-tool/mcp | server Model Context Protocol yang dijalankan pihak lain, dipetakan ke mcp-remote, yang tidak menjalankan apa pun |
agent | local/ai-agent/mcp-client | agen, yang dihubungkan ke search melalui soket tools miliknya |
Dua Releases berbagi satu Aggregate yang sama, masing-masing dengan Manifest sendiri:
| Release | Manifest | target | asal alamat lengkapnya |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | Secret yang sudah ada di namespace: core/referenced-secret yang diikat ke helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | referensi variabel Compose: core/secret-value yang diikat ke compose/dotenv-secret |
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example mcp-address-from-secretKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd mcp-address-from-secretBuild
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/Setiap Release menulis ke direktorinya sendiri, sehingga kedua pohon hasil render dapat berdampingan dan dapat dibandingkan secara berdampingan.
.aggrega-config.yaml mencantumkan catalog/ milik workspace ini, yang memuat agen dan kedua Recipes-nya; semua hal lainnya diresolusi dari hub.aggrega.ai, registry default yang disebutnya. Dengan checkout katalog pustaka standar (cara mendapatkannya) yang disebut lewat --catalog, setiap entitas diresolusi dari kedua direktori tersebut, sehingga build juga selesai dengan --offline, yang menolak setiap akses jaringan. --auto-pull menulis lockfile setiap Release selama build; lockfile dan keluaran hasil render dihasilkan, bukan dikirimkan.
Build Kubernetes mencetak keluaran berikut, dengan <workspace> mewakili folder
contoh ini:
Pull complete: release-helm.lock (entities=11, source_artifacts=0, external_inputs=0) 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: 2 files written to <workspace>/distBuild compose mencetak baris yang sama untuk release-compose.yaml, dengan pemberitahuannya
menyebut core/secret-value, dan menulis satu file. Baris notice: berkaitan dengan
Feature kredensial yang dilampirkan Release: Feature tersebut menerima locator secret,
origin, dari values milik pengembang atau infra milik operator, dan
pemberitahuan tersebut melaporkan bahwa satu leaf dideklarasikan di kedua pilar. Hal ini tidak mengubah verdict apa pun
dan tidak mengubah satu byte pun hasil render.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `mcp-address-from-secret`, panggil alat `scaffold` sekali dengan `example` diatur ke `mcp-address-from-secret` dan tanpa `dir`: alat ini menulis contoh ke folder `mcp-address-from-secret` yang baru. Kemudian panggil alat `build` sekali untuk setiap Release, dengan urutan ini — `release-helm.yaml` dan `release-compose.yaml` — setiap kali dengan `workspace_root` diatur ke `mcp-address-from-secret`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis oleh setiap build; file tersebut berada di bawah `mcp-address-from-secret/dist/`.Tool menyimpan alamat tanpa kuncinya
Dari release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote membaca host, port, dan skema yang dipublikasikannya dari alamat
tersebut, lalu menghasilkan satu file untuk tool: sebuah Service ExternalName yang memetakan
nama di dalam klaster ke host tersebut. Seluruh spec dari
dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Jadi, alamat yang disimpan tool setidaknya memerlukan skema dan host, dan tidak menyimpan
sedikit pun bagian yang membawa kunci. compose/mcp-remote sama sekali tidak mendefinisikan layanan
untuk tool tersebut.
Koneksi agen menyimpan seluruh alamat
Component milik agen mendeklarasikan dua slot rahasia pada soket tools-nya. Dari
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, tanpa
deskripsi:
tools: selector: "component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http" valueSchema: unauthenticated: type: boolean default: false featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] endpoint: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]credential menyimpan kunci yang disajikan agen dalam header permintaan; endpoint menyimpan
seluruh alamat, untuk server yang membaca kuncinya dari alamat itu sendiri.
unauthenticated adalah pernyataan koneksi itu sendiri bahwa alatnya tidak menerima
kredensial, dan tidak mengubah apa pun yang dirender agen. Ketiganya berada pada
koneksi, sehingga agen yang menjangkau beberapa server menyimpan rahasia setiap server pada
koneksi server tersebut.
Release mengisi endpoint pada koneksi yang dirangkai oleh Aggregate. Dari
release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressRelease tidak menulis values, sehingga origin berada di infra, dan kunci data yang dibaca
dari Secret adalah nilai bawaan Feature, yaitu value. Manifest mengikat
core/referenced-secret ke helm/k8s-existing-secret, yang membaca origin sebagai
nama Secret yang sudah ada di namespace dan tidak merender apa pun. Secret tersebut
dibuat di luar Release, oleh siapa pun yang men-deploy-nya:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'Kontainer agen membaca alamat dari Secret tersebut. env dari
dist/kubernetes/helm/agent-deployment.yaml:
env: - name: MCP_URL_SEARCH valueFrom: secretKeyRef: name: search-mcp-address key: value - name: MCP_HOST_SEARCH value: mcp.example.comMCP_URL_SEARCH adalah seluruh alamat, dibaca dari Secret berdasarkan nama dan kunci data;
MCP_HOST_SEARCH adalah host yang dipublikasikan alat. dist/kubernetes/helm/ hanya berisi
Deployment agen dan Service alat: tidak ada Secret yang
dirender, dan tidak ada file yang memuat kunci.
Pada Docker Compose
Compose tidak memiliki referensi rahasia, sehingga Release compose mengisi slot yang sama dengan
core/secret-value, dengan origin berupa referensi variabel Compose. Dari
release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret menyampaikan referensi sebagaimana tertulis, dan layanan
agen memuatnya. environment dari layanan agent dalam
dist/local/compose/docker-compose.yaml, yang hanya mendefinisikan layanan tersebut:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose menyubstitusi SEARCH_MCP_URL saat stack dimulai — dari
lingkungan shell, file yang disebutkan dengan --env-file, atau file .env di
direktori proyek — sehingga file hanya memuat referensinya.
Cara Recipes agen membaca slot
Setiap koneksi pada soket tools menjadi variabel lingkungan yang dinamai menurut alias koneksi dalam huruf kapital: MCP_HOST_<ALIAS> dari host yang dipublikasikan tool, dan MCP_URL_<ALIAS> dari alamat yang dipublikasikan tool — kecuali jika koneksi membawa secret endpoint, dalam hal ini MCP_URL_<ALIAS> adalah secret tersebut dan alamat yang dipublikasikan sama sekali tidak dikirimkan. Koneksi yang membawa credential menambahkan MCP_CREDENTIAL_<ALIAS>, dan MCP_CREDENTIAL_HEADER_<ALIAS>, yaitu header permintaan yang dipublikasikan tool untuk menyajikannya.
- Di Kubernetes secret adalah entri lampiran yang menyebut koneksi dan
slot —
connection: search,from: endpoint,as: env— yang diubah oleh provider menjadisecretKeyRefdi atas, dengan membaca nama Secret dan kunci datanya dari apa yang dipublikasikanhelm/k8s-existing-secret. - Di Docker Compose secret tiba di pipa inject agen di bawah
kunci tempat lampirannya sendiri mengirimkannya,
values.key, dan Recipe menulis nilai tersebut ke dalam lingkungan layanan.
Jika ditulis ke dalam infra.endpoint milik tool, kunci akan ikut ke mana pun
alamat yang dipublikasikan pergi: MCP_URL_SEARCH milik agen membawanya sebagai nilai
literal, di Deployment pada Kubernetes dan di lingkungan layanan dalam berkas
Compose, karena realisasi referensi memublikasikan alamat sebagaimana
ditulis.
Batasan
-
Di Docker Compose, dua secret yang dilampirkan oleh Release saja ke satu agen saling bertabrakan. Setiap lampiran
core/secret-valueyang dibuat oleh Release dikirim di bawah kunci bawaan Feature,value, sehingga lampiran kedua pada agen yang sama — alamat server lain, atau kredensial di samping yang ini — menghentikan build. Sebuah Release yang melampirkanendpointdancredentialsekaligus kesearchmencetak:[… omitted: what resolving the lockfile prints, the same halt among it, and the notice about core/secret-value][OPS_ERROR E0318] release-compose.yaml at .spec.boundaries.main.components.agent.uses.tools.search.features.credentialduplicate delivery key across two attachments: an attachment's FeatureRecipe writes a delivery key another attachment already delivered ("value", mechanism "env", attachment "search.credential", delivered first by attachment "search.endpoint"). Give one of the two attachments a key of its own, or attach one fewer: the key this attachment delivers under is chosen by its FeatureRecipe, which can read the attachment's own values and infra, and the other's is chosen the same way or by its own inject block where it delivered through one. A Release sets an attachment's infra and never its values, so where a key is chosen by a value, attach that attachment in the Aggregate with the value, and keep giving the rest from the Release.Kunci tersebut adalah daun
values, yang hanya ditulis oleh Aggregate, sehingga Aggregate yang mendeklarasikan salah satu dari kedua lampiran itu dan menamaivalues.key-nya menghindarinya: Recipe compose milik agen membaca setiap secret di bawah kunci yang dinamai oleh lampirannya sendiri. Kubernetes tidak memiliki batasan seperti itu, karena setiap secret di sana adalah referensi ke sebuah Secret berdasarkan nama dan kunci data, bukan nilai yang dikirim di bawah sebuah kunci. -
Kunci di path alamat. Jika server membaca kuncinya dari path dan bukan dari query string, alamat tool adalah alamat tersebut tanpa bagian path itu, dan Secret menyimpan alamat secara utuh.
-
Host ditulis dua kali, secara terbuka di alamat tool dan di dalam Secret, dan tidak ada yang memeriksa bahwa keduanya sama, karena compiler tidak pernah membaca Secret.
Menyusun alamat saat run time hanya dari kunci, dengan referensi $(VAR)
di dalam variabel biasa, hanya berfungsi di Kubernetes: Kubernetes mengekspansi
referensi seperti itu dari entri yang tercantum sebelumnya di dalam container, dan
provider helm mencantumkan entri yang dibacanya dari Secret sebelum variabel
biasa, sedangkan Docker Compose tidak mengekspansi referensi $(VAR) apa pun di antara
entri environment sebuah service.
Menyesuaikannya
- Server yang juga memeriksa header. Lampirkan
credentialpada koneksi yang sama. Agen menerimaMCP_CREDENTIAL_SEARCHdan header tempat menyajikannya,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, kecuali jika Release menyebutkan header milik server itu sendiri dalaminfra.credential_headermilik tool. Pada Docker Compose, sebutkan kunci salah satu dari keduanya di Aggregate, seperti di atas. - Beberapa server. Hubungkan satu koneksi per server pada soket
tools. Variabel setiap koneksi membawa aliasnya, dan setiap koneksi menyimpan secret-nya sendiri. - Server yang membaca kuncinya hanya dari header. Jangan sertakan
endpoint, danMCP_URL_<ALIAS>adalah alamat yang dipublikasikan oleh tool.
Determinisme
Kedua Releases di-build dengan --verify-determinism, yang merender setiap node dua kali
dan membandingkan byte yang dihasilkan:
aggrega build --release release-helm.yaml --verify-determinismMem-build ulang salah satunya dari tree yang bersih menghasilkan kembali output rendernya secara identik byte demi byte.
Berkas
aggregate.yaml— tool dan agen, dihubungkan melalui sockettools, tanpa secret yang dilampirkan.manifest-helm.yaml,manifest-compose.yaml— tool kemcp-remote, agen ke Recipe miliknya sendiri, dan Feature kredensial yang digunakan setiap target.release-helm.yaml,release-compose.yaml— alamat tool tanpa kuncinya, image agen, dan secretendpointpada koneksi agen.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— agen: sockettoolsmiliknya dengan slotcredentialdanendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— agen pada setiap target..aggrega-config.yaml— tumpukan pencarian katalog dan registri.build-release.sh— membangun satu Release, sambil menampilkan perintahaggrega buildyang setara.
Untuk kunci yang diberikan agen dalam sebuah header, yang disimpan pada koneksi tempat kunci itu diberikan, lihat connection-credentials. Model yang mendasari keduanya adalah Credential Model, dan realisasi tool dijelaskan dengan label transport tool di AI Features.