Địa chỉ của một công cụ lấy từ một Secret — một máy chủ Model Context Protocol đọc khóa từ chính địa chỉ của nó
Một số máy chủ Model Context Protocol do bên khác vận hành đọc khóa từ
chính địa chỉ của chúng — https://mcp.example.com/mcp?api_key=<key> — thay vì
từ một header của yêu cầu. Một địa chỉ như vậy không thể được ghi vào công cụ theo cách
một địa chỉ thông thường được ghi: công cụ công bố địa chỉ đúng như được viết, nên khóa sẽ
đến mọi tệp mà địa chỉ đến.
Workspace này giữ địa chỉ thành hai phần. Công cụ, core/ai-tool/mcp,
giữ địa chỉ mà không có phần mang khóa. Kết nối của agent
đến công cụ giữ toàn bộ địa chỉ dưới dạng một secret, và Release chỉ ra nơi nó
được lưu. Ví dụ này xây dựng cho Kubernetes và cho Docker Compose, và trên cả hai, không tệp
được render nào mang khóa.
Agent được khai báo trong catalog riêng của workspace này, nên socket giữ địa chỉ được viết đầy đủ tại đây. Các runtime agent của thư viện chuẩn core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk và mastra, cùng các nền tảng core/ai-agent/flowise và n8n, khai báo một socket tools với cùng hai slot. Công cụ, hai Features về thông tin xác thực và các hiện thực của chúng được cung cấp trong catalog của thư viện chuẩn.
Những gì ví dụ này xây dựng
| instance | Component trong catalog | vai trò ở đây |
|---|---|---|
search | core/ai-tool/mcp | một máy chủ Model Context Protocol do bên khác vận hành, được ánh xạ tới mcp-remote, vốn không chạy gì cả |
agent | local/ai-agent/mcp-client | agent, được nối với search qua socket tools của nó |
Hai Releases dùng chung một Aggregate, mỗi Release có Manifest riêng:
| Release | Manifest | đích | nguồn của địa chỉ đầy đủ |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | một Secret mà namespace đã có sẵn: core/referenced-secret gắn với helm/k8s-existing-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | một tham chiếu biến Compose: core/secret-value gắn với compose/dotenv-secret |
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example mcp-address-from-secretSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
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/Mỗi Release ghi vào thư mục riêng của nó, nên hai cây kết xuất cùng tồn tại và có thể được so sánh song song.
.aggrega-config.yaml liệt kê catalog/ của chính workspace này, nơi chứa agent và hai Recipes của nó; mọi thứ khác được phân giải từ hub.aggrega.ai, registry mặc định mà tệp này chỉ định. Khi một bản checkout catalog thư viện chuẩn (lấy ở đâu) được chỉ định bằng --catalog, mọi entity đều được phân giải từ hai thư mục đó, nên bản build cũng hoàn tất với --offline, tùy chọn từ chối mọi truy cập mạng. --auto-pull ghi lockfile của mỗi Release trong quá trình build; các lockfile và đầu ra kết xuất được sinh ra, không được phân phối kèm.
Bản build Kubernetes in ra như sau, với <workspace> đại diện cho thư mục
của ví dụ này:
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>/distBản build compose in ra cùng các dòng đó cho release-compose.yaml, với thông báo
nêu tên core/secret-value, và ghi ra một tệp. Dòng notice: nói về
Feature thông tin xác thực mà Release gắn vào: nó nhận bộ định vị của secret,
origin, từ values của nhà phát triển hoặc infra của người vận hành, và
thông báo tư vấn này báo rằng một nút lá được khai báo ở cả hai trụ cột. Nó không thay đổi kết luận nào
và không thay đổi byte kết xuất nào.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `mcp-address-from-secret`, hãy gọi công cụ `scaffold` một lần với `example` được đặt thành `mcp-address-from-secret` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `mcp-address-from-secret` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-helm.yaml` và `release-compose.yaml` — mỗi lần với `workspace_root` được đặt thành `mcp-address-from-secret`, `release` được đặt thành tệp đó, `auto_pull` được đặt thành true và `write` được đặt thành true. Hãy cho tôi biết mỗi bản build đã ghi những tệp nào; chúng nằm trong `mcp-address-from-secret/dist/`.Công cụ giữ địa chỉ mà không có khóa của nó
Từ release-helm.yaml:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote đọc host, cổng và scheme mà nó công bố từ địa chỉ đó,
rồi xuất ra một tệp cho công cụ: một Service ExternalName ánh xạ một
tên trong cụm sang host. Toàn bộ spec của
dist/kubernetes/helm/search-service.yaml:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Vì vậy, địa chỉ mà công cụ giữ cần ít nhất một scheme và một host, và không chứa
gì của phần mang khóa. compose/mcp-remote hoàn toàn không định nghĩa service nào
cho công cụ.
Kết nối của agent giữ toàn bộ địa chỉ
Component của agent khai báo hai slot bí mật trên socket tools của nó. Trích từ
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, đã lược bỏ
phần mô tả:
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 giữ một khóa mà agent trình ra trong một header của yêu cầu; endpoint giữ
toàn bộ địa chỉ, dành cho một máy chủ đọc khóa của nó từ chính địa chỉ.
unauthenticated là tuyên bố riêng của kết nối rằng công cụ của nó không nhận
thông tin xác thực nào, và không thay đổi bất cứ thứ gì agent kết xuất. Cả ba nằm trên
kết nối, nên một agent kết nối tới nhiều máy chủ sẽ giữ bí mật của từng máy chủ trên
kết nối của máy chủ đó.
Release điền endpoint trên kết nối mà Aggregate đã nối. Trích từ
release-helm.yaml:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressMột Release không viết values, nên origin nằm trong infra, và khóa dữ liệu được đọc
từ Secret là giá trị mặc định của Feature, value. Manifest gắn
core/referenced-secret với helm/k8s-existing-secret, thành phần này đọc origin là
tên của một Secret mà namespace đã có sẵn và không kết xuất gì cả. Secret
được tạo bên ngoài Release, bởi người triển khai nó:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'Container của agent đọc địa chỉ từ đó. Phần env của
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 là toàn bộ địa chỉ, được đọc từ Secret theo tên và khóa dữ liệu;
MCP_HOST_SEARCH là host mà công cụ công bố. dist/kubernetes/helm/ chứa
Deployment của agent và Service của công cụ, ngoài ra không có gì khác: không Secret nào được
kết xuất, và không tệp nào mang khóa.
Trên Docker Compose
Compose không có tham chiếu bí mật, nên Release cho compose điền cùng slot đó bằng
core/secret-value, với origin là một tham chiếu biến Compose. Trích từ
release-compose.yaml:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret chuyển giao tham chiếu đúng như đã viết, và service của agent
mang nó. Phần environment của service agent trong
dist/local/compose/docker-compose.yaml, tệp định nghĩa service đó và không
service nào khác:
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose thay thế SEARCH_MCP_URL khi stack khởi động — từ
môi trường shell, một tệp được chỉ định bằng --env-file, hoặc tệp .env trong
thư mục dự án — nên tệp chỉ mang tham chiếu mà thôi.
Cách các Recipes của agent đọc slot
Mỗi kết nối trên socket tools trở thành các biến môi trường được đặt tên theo bí danh của kết nối viết hoa: MCP_HOST_<ALIAS> từ host mà tool công bố, và MCP_URL_<ALIAS> từ địa chỉ mà tool công bố — trừ khi kết nối mang một secret endpoint, khi đó MCP_URL_<ALIAS> là secret đó và địa chỉ được công bố hoàn toàn không được chuyển giao. Một kết nối mang credential sẽ thêm MCP_CREDENTIAL_<ALIAS>, và MCP_CREDENTIAL_HEADER_<ALIAS>, header yêu cầu mà tool công bố để trình bày credential đó.
- Trên Kubernetes, secret là một mục attachment nêu tên kết nối và
slot —
connection: search,from: endpoint,as: env— mà provider chuyển thànhsecretKeyRefở trên, đọc tên và data key của Secret từ những gìhelm/k8s-existing-secretcông bố. - Trên Docker Compose, secret đến trên inject pipe của agent dưới
key mà chính attachment của nó đã chuyển giao,
values.key, và Recipe ghi giá trị đó vào môi trường của service.
Nếu thay vào đó được ghi vào infra.endpoint của tool, key sẽ đi đến bất cứ đâu
địa chỉ được công bố đi đến: MCP_URL_SEARCH của agent mang nó như một giá trị
literal, trong Deployment trên Kubernetes và trong môi trường của service trong
file Compose, vì bản hiện thực tham chiếu công bố địa chỉ đúng như
đã viết.
Giới hạn
-
Trên Docker Compose, hai secret mà chỉ riêng Release gắn vào cùng một agent sẽ xung đột. Mỗi attachment
core/secret-valuemà một Release tạo ra đều chuyển giao dưới khóa mặc định của Feature làvalue, nên một attachment thứ hai trên cùng agent — địa chỉ của một server khác, hoặc một credential bên cạnh địa chỉ này — sẽ dừng quá trình build. Một Release gắn cảendpointlẫncredentialvàosearchsẽ in ra:[… 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.Khóa là một lá
values, mà chỉ Aggregate ghi, nên một Aggregate khai báo một trong hai attachment và đặt tên chovalues.keycủa nó sẽ tránh được điều này: Recipe compose của agent đọc mỗi secret dưới khóa mà chính attachment của nó đặt tên. Kubernetes không có giới hạn như vậy, vì ở đó mỗi secret là một tham chiếu tới một Secret theo tên và khóa dữ liệu, chứ không phải một giá trị được chuyển giao dưới một khóa. -
Khóa nằm trong đường dẫn của địa chỉ. Khi server đọc khóa từ đường dẫn thay vì từ chuỗi truy vấn, địa chỉ của tool là địa chỉ đã bỏ phần đó của đường dẫn, và Secret giữ toàn bộ địa chỉ.
-
Host được ghi hai lần, dạng thuần trong địa chỉ của tool và bên trong Secret, và không có gì kiểm tra rằng hai giá trị khớp nhau, vì trình biên dịch không bao giờ đọc một Secret.
Việc ghép địa chỉ lúc chạy chỉ từ khóa, bằng một tham chiếu $(VAR)
trong một biến thông thường, chỉ hoạt động trên Kubernetes: Kubernetes mở rộng
tham chiếu như vậy từ các mục được liệt kê trước nó trong container, và
provider helm liệt kê các mục nó đọc từ một Secret trước các biến
thông thường, trong khi Docker Compose không mở rộng tham chiếu $(VAR) nào giữa các mục
environment của một service.
Điều chỉnh ví dụ
- Một máy chủ cũng kiểm tra một header. Gắn
credentialtrên cùng kết nối. Agent nhậnMCP_CREDENTIAL_SEARCHvà header để trình nó dưới đó,MCP_CREDENTIAL_HEADER_SEARCH:Authorization, trừ khi Release nêu tên header riêng của máy chủ tronginfra.credential_headercủa công cụ. Trên Docker Compose, hãy đặt tên khóa của một trong hai trong Aggregate, như ở trên. - Nhiều máy chủ. Nối một kết nối cho mỗi máy chủ trên socket
tools. Các biến của mỗi kết nối mang alias của nó, và mỗi kết nối giữ các secret riêng của nó. - Một máy chủ chỉ đọc khóa của nó từ một header. Bỏ
endpointđi, vàMCP_URL_<ALIAS>là địa chỉ mà công cụ công bố.
Tính tất định
Cả hai Releases đều build được với --verify-determinism, cờ này render mỗi nút hai lần
và so sánh các byte được xuất ra:
aggrega build --release release-helm.yaml --verify-determinismBuild lại bất kỳ Release nào trong hai từ một cây sạch đều tái tạo đầu ra đã render của nó chính xác đến từng byte.
Các tệp
aggregate.yaml— công cụ và agent, được nối với nhau qua sockettools, không gắn secret nào.manifest-helm.yaml,manifest-compose.yaml— công cụ tớimcp-remote, agent tới Recipe riêng của nó, và Feature thông tin xác thực mà mỗi target sử dụng.release-helm.yaml,release-compose.yaml— địa chỉ của công cụ không kèm khóa, image của agent, và secretendpointtrên kết nối của agent.catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— agent: sockettoolscủa nó với các slotcredentialvàendpoint.catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml,catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— agent trên mỗi target..aggrega-config.yaml— ngăn xếp tìm kiếm catalog và registry.build-release.sh— build một Release, in ra lệnhaggrega buildtương đương.
Với một khóa mà agent trình bày trong header, được giữ trên chính kết nối mà nó được trình bày, xem connection-credentials. Mô hình đứng sau cả hai là Mô hình thông tin xác thực, và các hiện thực hóa của công cụ được mô tả cùng nhãn transport của công cụ trong Các Features AI.