Bir aracın adresinin bir Secret'tan alınması — anahtarını kendi adresinden okuyan bir Model Context Protocol sunucusu
Başkası tarafından çalıştırılan bazı Model Context Protocol sunucuları anahtarlarını bir istek
başlığından değil, kendi adreslerinden okur — https://mcp.example.com/mcp?api_key=<key>. Böyle bir adres,
sıradan bir adres gibi araca yazılamaz: araç, adresini yazıldığı gibi yayımlar; bu nedenle anahtar,
adresin ulaştığı her dosyaya ulaşırdı.
Bu çalışma alanı adresi iki parça hâlinde tutar. Araç, yani core/ai-tool/mcp,
adresi anahtarı taşıyan kısım olmadan tutar. Ajanın araca olan bağlantısı ise
adresin tamamını bir gizli değer olarak tutar ve Release bu değerin nerede
bulunduğunu belirtir. Kubernetes ve Docker Compose için oluşturulur ve her ikisinde de
işlenen hiçbir dosya anahtarı taşımaz.
Ajan bu çalışma alanının kendi kataloğunda bildirilir; bu nedenle adresi tutan soket burada eksiksiz olarak yazılmıştır. Standart kütüphanedeki ajan çalışma ortamları core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk ve mastra ile core/ai-agent/flowise ve n8n platformları, aynı iki yuvaya sahip bir tools soketi bildirir. Araç, iki kimlik bilgisi Features’ı ve bunların gerçekleştirimleri standart kütüphane kataloğuyla birlikte gelir.
Ne oluşturur
| örnek | katalog Component’i | burada ne olduğu |
|---|---|---|
search | core/ai-tool/mcp | başka birinin çalıştırdığı, hiçbir şey çalıştırmayan mcp-remote’a eşlenmiş bir Model Context Protocol sunucusu |
agent | local/ai-agent/mcp-client | tools soketi üzerinden search’e bağlanan ajan |
İki Release, her biri kendi Manifest’ine sahip olarak tek Aggregate’i paylaşır:
| Release | Manifest | hedef | adresin tamamının geldiği yer |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | ad alanının zaten barındırdığı bir Secret: helm/k8s-existing-secret’e bağlanan core/referenced-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | bir Compose değişken başvurusu: compose/dotenv-secret’e bağlanan core/secret-value |
Örneği oluşturun
Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example mcp-address-from-secretArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd mcp-address-from-secretDerleme
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/Her Release kendi dizinine yazar; böylece işlenmiş iki ağaç bir arada bulunur ve yan yana karşılaştırılabilir.
.aggrega-config.yaml, bu çalışma alanının ajanı ve onun iki Recipes’ini barındıran kendi catalog/ dizinini listeler; geri kalan her şey bu dosyanın adlandırdığı varsayılan kayıt defteri olan hub.aggrega.ai’den çözümlenir. Standart kitaplık kataloğunun bir çalışma kopyası (nereden edinilir) --catalog ile adlandırıldığında her varlık bu iki dizinden çözümlenir; böylece derleme, her ağ erişimini reddeden --offline ile de tamamlanır. --auto-pull her Release’in kilit dosyasını derleme sırasında yazar; kilit dosyaları ve işlenmiş çıktı üretilir, dağıtılmaz.
Kubernetes derlemesi, <workspace> bu örneğin klasörünü temsil edecek şekilde
şunu yazdırır:
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>/distCompose derlemesi release-compose.yaml için aynı satırları, bildirimi
core/secret-value’yu adlandırarak yazdırır ve tek bir dosya yazar. notice: satırı,
Release’in eklediği kimlik bilgisi Feature’ı ile ilgilidir: bu Feature gizli bilginin konum belirtecini,
origin’i, geliştiricinin values’undan ya da operatörün infra’sından kabul eder ve
tavsiye niteliğindeki bildirim, bir yaprağın her iki sütunda da bildirildiğini raporlar. Hiçbir kararı
ve işlenmiş hiçbir baytı değiştirmez.
Bir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz klasör oluşturmayın. Çalışma alanı klasöründe henüz `mcp-address-from-secret` klasörü yoksa `scaffold` aracını `example` değeri `mcp-address-from-secret` olacak şekilde ve `dir` olmadan bir kez çağırın: araç örneği yeni bir `mcp-address-from-secret` klasörüne yazar. Ardından `build` aracını her Release için bir kez, şu sırayla — `release-helm.yaml` ve `release-compose.yaml` — her seferinde `workspace_root` değeri `mcp-address-from-secret`, `release` değeri o dosya, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Her derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `mcp-address-from-secret/dist/` altındadır.Araç, adresi anahtarı olmadan tutar
release-helm.yaml dosyasından:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote, yayımladığı ana makineyi, portu ve şemayı bu adresten okur ve araç için tek bir dosya üretir: küme içi bir adı ana makineye eşleyen bir ExternalName Service.
dist/kubernetes/helm/search-service.yaml dosyasının spec bölümünün tamamı:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Dolayısıyla aracın tuttuğu adresin en azından bir şemaya ve bir ana makineye ihtiyacı vardır ve adres, anahtarı taşıyan kısımdan hiçbir şey tutmaz. compose/mcp-remote, araç için hiçbir servis tanımlamaz.
Ajanın bağlantısı adresin tamamını tutar
Ajanın Component’i, tools soketinde iki gizli bilgi yuvası bildirir. Açıklamalar çıkarılmış olarak
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml dosyasından:
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, ajanın bir istek başlığında sunduğu anahtarı tutar; endpoint ise anahtarını adresin kendisinden okuyan bir sunucu için adresin tamamını tutar.
unauthenticated, bağlantının, aracının kimlik bilgisi almadığına dair kendi beyanıdır ve ajanın işlediği hiçbir şeyi değiştirmez. Üçü de bağlantı üzerinde bulunur; bu nedenle birkaç sunucuya erişen bir ajan, her sunucunun gizli bilgisini o sunucunun bağlantısında tutar.
Release, Aggregate’in bağladığı bağlantıdaki endpoint yuvasını doldurur.
release-helm.yaml dosyasından:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressBir Release values yazmaz; bu nedenle origin, infra içindedir ve Secret’tan okunan veri anahtarı Feature’ın varsayılanı olan value’dur. Manifest,
core/referenced-secret’i helm/k8s-existing-secret’e bağlar; bu da origin’i ad alanında zaten bulunan bir Secret’ın adı olarak okur ve hiçbir şey işlemez. Secret, Release’in dışında, onu dağıtan kişi tarafından oluşturulur:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'Ajanın konteyneri adresi buradan okur.
dist/kubernetes/helm/agent-deployment.yaml dosyasının env bölümü:
env: - name: MCP_URL_SEARCH valueFrom: secretKeyRef: name: search-mcp-address key: value - name: MCP_HOST_SEARCH value: mcp.example.comMCP_URL_SEARCH, Secret’tan adı ve veri anahtarıyla okunan adresin tamamıdır;
MCP_HOST_SEARCH ise aracın yayımladığı ana makinedir. dist/kubernetes/helm/, ajanın Deployment’ını ve aracın Service’ini tutar, başka hiçbir şeyi tutmaz: hiçbir Secret işlenmez ve hiçbir dosya anahtarı taşımaz.
Docker Compose üzerinde
Compose’da gizli bilgi referansı yoktur; bu nedenle compose Release’i aynı yuvayı, kaynağı bir Compose değişken referansı olan
core/secret-value ile doldurur.
release-compose.yaml dosyasından:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret referansı yazıldığı gibi iletir ve ajanın servisi onu taşır. Yalnızca o servisi tanımlayan
dist/local/compose/docker-compose.yaml dosyasındaki agent servisinin environment bölümü:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose, SEARCH_MCP_URL değişkenini yığın başlatıldığında yerine koyar — kabuk ortamından, --env-file ile belirtilen bir dosyadan ya da proje dizinindeki .env dosyasından — bu nedenle dosya yalnızca referansı taşır.
Ajanın Recipes’i yuvayı nasıl okur
tools soketindeki her bağlantı, bağlantının takma adının büyük harfli hâliyle adlandırılan ortam değişkenlerine dönüşür: aracın yayımladığı ana makineden MCP_HOST_<ALIAS> ve aracın yayımladığı adresten MCP_URL_<ALIAS>; ancak bağlantı bir endpoint gizli değeri taşıyorsa MCP_URL_<ALIAS> o gizli değerdir ve yayımlanan adres hiç iletilmez. Bir credential taşıyan bağlantı MCP_CREDENTIAL_<ALIAS> değişkenini ve aracın, kimlik bilgisinin altında sunulması için yayımladığı istek başlığı olan MCP_CREDENTIAL_HEADER_<ALIAS> değişkenini ekler.
- Kubernetes’te gizli değer, bağlantıyı ve yuvayı adlandıran bir ek girdisidir (
connection: search,from: endpoint,as: env); sağlayıcı bunu, Secret’ın adını ve veri anahtarınıhelm/k8s-existing-secretöğesinin yayımladığından okuyarak yukarıdakisecretKeyRefyapısına dönüştürür. - Docker Compose’da gizli değer, ajanın inject borusuna, kendi ekinin onu ilettiği anahtar olan
values.keyaltında ulaşır ve Recipe bu değeri servisin ortamına yazar.
Anahtar bunun yerine aracın infra.endpoint alanına yazılırsa, yayımlanan adres nereye giderse oraya gider: ajanın MCP_URL_SEARCH değişkeni onu Kubernetes’te Deployment içinde, Compose dosyasında ise servisin ortamında düz bir değer olarak taşır; çünkü başvuru gerçekleştirimi adresi yazıldığı gibi yayımlar.
Sınırlar
-
Docker Compose üzerinde, Release’in tek başına bir ajana eklediği iki gizli değer çakışır. Bir Release’in yaptığı her
core/secret-valueeklemesi değeri Feature’ın varsayılan anahtarı olanvaluealtında iletir; bu nedenle aynı ajana yapılan ikinci bir ekleme — başka bir sunucunun adresi ya da bunun yanındaki bir kimlik bilgisi — derlemeyi durdurur.search’e hem birendpointhem de bircredentialekleyen bir Release şunu yazdırır:[… 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.Anahtar bir
valuesyaprağıdır ve onu yalnızca Aggregate yazar; bu nedenle iki eklemeden birini bildiren ve onunvalues.keydeğerini adlandıran bir Aggregate bu sorundan kaçınır: ajanın compose Recipe’i her gizli değeri kendi eklemesinin adlandırdığı anahtar altında okur. Kubernetes’te böyle bir sınır yoktur, çünkü orada her gizli değer bir anahtar altında iletilen bir değer değil, bir Secret’a adı ve veri anahtarıyla yapılan bir başvurudur. -
Adresin yolunda bir anahtar. Sunucu anahtarını sorgu dizesinden değil de yoldan okuyorsa, aracın adresi yolun o kısmı çıkarılmış adrestir ve Secret adresin tamamını tutar.
-
Ana makine iki kez yazılır: aracın adresinde açıkça ve Secret’ın içinde; ikisinin uyuştuğunu hiçbir şey denetlemez, çünkü derleyici bir Secret’ı hiçbir zaman okumaz.
Adresi çalışma zamanında yalnızca anahtardan, düz bir değişkendeki bir $(VAR)
başvurusuyla birleştirmek yalnızca Kubernetes üzerinde çalışır: Kubernetes böyle bir
başvuruyu kapsayıcıda kendisinden önce listelenen girdilerden genişletir ve helm
provider’ı bir Secret’tan okuduğu girdileri düz değişkenlerden önce listeler;
Docker Compose ise bir servisin ortam girdileri arasında hiçbir $(VAR) başvurusunu
genişletmez.
Uyarlama
- Bir header’ı da denetleyen bir sunucu. Aynı bağlantıya
credentialekleyin. Agent,MCP_CREDENTIAL_SEARCHdeğerini ve bunu sunacağı header’ı,MCP_CREDENTIAL_HEADER_SEARCHdeğerini alır: Release, aracıninfra.credential_headeralanında sunucunun kendi header’ını belirtmedikçe buAuthorizationolur. Docker Compose’da, yukarıda olduğu gibi, ikisinden birinin anahtarını Aggregate’te belirtin. - Birden çok sunucu.
toolssoketinde her sunucu için bir bağlantı kurun. Her bağlantının değişkenleri kendi takma adını taşır ve her bağlantı kendi gizli değerlerini tutar. - Anahtarını yalnızca bir header’dan okuyan bir sunucu.
endpointeklemeyin; bu durumdaMCP_URL_<ALIAS>, aracın yayımladığı adres olur.
Determinizm
Her iki Releases de --verify-determinism ile derlenir; bu seçenek her düğümü iki kez işler ve üretilen baytları karşılaştırır:
aggrega build --release release-helm.yaml --verify-determinismHerhangi birini temiz bir ağaçtan yeniden derlemek, işlenmiş çıktısını bayt bayt aynı şekilde yeniden üretir.
Dosyalar
aggregate.yaml— araç ve ajan,toolssoketi üzerinden bağlanmış, hiçbir secret eklenmemiş.manifest-helm.yaml,manifest-compose.yaml— aracımcp-remote’e, ajanı kendi Recipe’sine eşler ve her hedefin kullandığı kimlik bilgisi Feature’ını belirtir.release-helm.yaml,release-compose.yaml— aracın anahtarı olmayan adresi, ajanın imajı ve ajanın bağlantısındakiendpointsecret’ı.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— ajan:credentialveendpointyuvalarıyla birliktetoolssoketi.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— her hedefteki ajan..aggrega-config.yaml— katalog arama yığını ve kayıt defteri.build-release.sh— tek bir Release derler ve eşdeğeraggrega buildkomutunu yazdırır.
Ajanın bir başlıkta sunduğu ve sunulduğu bağlantıda tutulan bir anahtar için connection-credentials sayfasına bakın. Her ikisinin ardındaki model Kimlik Bilgisi Modeli’dir ve aracın gerçekleştirimleri AI Features bölümünde araç aktarım etiketiyle açıklanmıştır.