Secret から得るツールのアドレス — 自身のアドレスからキーを読み取る Model Context Protocol サーバー
他者が運用する Model Context Protocol サーバーの中には、リクエストヘッダーからではなく、自身のアドレス — https://mcp.example.com/mcp?api_key=<key> — からキーを読み取るものがあります。このようなアドレスは、通常のアドレスと同じようにツールに書き込むことはできません。ツールはアドレスを書かれたとおりに公開するため、アドレスが届くすべてのファイルにキーが届いてしまいます。
このワークスペースでは、アドレスを 2 つの部分に分けて保持します。ツール core/ai-tool/mcp は、キーを含む部分を除いたアドレスを保持します。エージェントからツールへの接続は、アドレス全体をシークレットとして保持し、その保管場所を Release が指定します。Kubernetes 向けにも Docker Compose 向けにもビルドでき、どちらでもレンダリングされたファイルにキーは含まれません。
エージェントはこのワークスペース独自のカタログで宣言されているため、アドレスを保持するソケットをここで完全に記述しています。標準ライブラリのエージェントランタイム core/ai-agent/openai-agents-sdk、claude-agent-sdk、agent-framework、google-adk、mastra、およびプラットフォーム core/ai-agent/flowise と n8n も、同じ 2 つのスロットを持つ tools ソケットを宣言しています。ツール、2 つの認証情報 Features、およびそれらの実現は、標準ライブラリのカタログに含まれています。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
search | core/ai-tool/mcp | 他者が運用する Model Context Protocol サーバー。何も実行しない mcp-remote にマッピングされます |
agent | local/ai-agent/mcp-client | エージェント。tools ソケットを通じて search に接続されます |
2 つの Releases が 1 つの Aggregate を共有し、それぞれが独自の Manifest を持ちます。
| Release | Manifest | ターゲット | アドレス全体の取得元 |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | 名前空間がすでに保持している Secret:helm/k8s-existing-secret にバインドされた core/referenced-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | Compose の変数参照:compose/dotenv-secret にバインドされた core/secret-value |
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example mcp-address-from-secretその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd mcp-address-from-secretビルド
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/各 Release はそれぞれ専用のディレクトリに書き出すため、レンダリングされた 2 つのツリーは共存でき、 並べて比較できます。
.aggrega-config.yaml は、このワークスペース自身の catalog/ を挙げます。ここにはエージェントとその 2 つの Recipes が含まれます。それ以外のすべては、このファイルが指定するデフォルトレジストリ hub.aggrega.ai から解決されます。標準ライブラリのカタログのチェックアウト(入手先)を --catalog で指定すると、すべてのエンティティがこの 2 つのディレクトリから解決されるため、ビルドはあらゆるネットワークアクセスを拒否する --offline を指定しても完了します。--auto-pull はビルド中に各 Release のロックファイルを書き出します。ロックファイルとレンダリングされた出力は生成物であり、配布されるものではありません。
Kubernetes のビルドは次のように出力します。<workspace> はこの例の
フォルダを表します。
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 のビルドは release-compose.yaml について同じ行を出力し、その notice は
core/secret-value を挙げ、ファイルを 1 つ書き出します。notice: の行は、
Release が付加する認証情報の Feature に関するものです。この Feature はシークレットのロケーター
origin を開発者の values またはオペレーターの infra から受け取り、
このアドバイザリは 1 つのリーフが両方の柱で宣言されていることを報告します。判定も
レンダリングされるバイトも一切変わりません。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `mcp-address-from-secret` フォルダーがない場合は、`example` を `mcp-address-from-secret` に設定し、`dir` を指定せずに `scaffold` ツールを一度呼び出してください。これにより、例が新しい `mcp-address-from-secret` フォルダーに書き込まれます。次に、`release-helm.yaml`、`release-compose.yaml` の順に、各 Release について `build` ツールを一度ずつ呼び出してください。毎回、`workspace_root` を `mcp-address-from-secret`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。ファイルは `mcp-address-from-secret/dist/` の下にあります。ツールはキーを含まないアドレスを保持する
release-helm.yaml より:
search: infra: endpoint: https://mcp.example.com/mcphelm/mcp-remote は、公開するホスト、ポート、スキームをそのアドレスから読み取り、ツール用に 1 つのファイルを出力します。クラスタ内の名前をホストにマッピングする ExternalName Service です。
dist/kubernetes/helm/search-service.yaml の spec 全体:
spec: type: ExternalName externalName: mcp.example.com ports: - port: 443したがって、ツールが保持するアドレスには少なくともスキームとホストが必要であり、キーを運ぶ部分は一切含みません。compose/mcp-remote はツール用のサービスをまったく定義しません。
エージェントの接続はアドレス全体を保持する
エージェントの Component は、tools ソケットに 2 つのシークレットスロットを宣言します。
catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml より(説明は省略):
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 は、エージェントがリクエストヘッダーで提示するキーを保持します。endpoint は、アドレス自体からキーを読み取るサーバー向けに、アドレス全体を保持します。
unauthenticated は、そのツールが認証情報を受け取らないことを接続自身が表明するもので、エージェントがレンダリングする内容は何も変わりません。3 つはいずれも接続上にあるため、複数のサーバーに接続するエージェントは、各サーバーのシークレットをそのサーバーの接続上に保持します。
Release は、Aggregate が配線した接続上の endpoint を埋めます。
release-helm.yaml より:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressRelease は values を書かないため、origin は infra にあり、Secret から読み取るデータキーは Feature のデフォルトである value です。Manifest は
core/referenced-secret を helm/k8s-existing-secret にバインドします。これは origin を名前空間がすでに保持している Secret の名前として読み取り、何もレンダリングしません。Secret は Release の外で、デプロイする側によって作成されます:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'エージェントのコンテナは、そこからアドレスを読み取ります。
dist/kubernetes/helm/agent-deployment.yaml の env:
env: - name: MCP_URL_SEARCH valueFrom: secretKeyRef: name: search-mcp-address key: value - name: MCP_HOST_SEARCH value: mcp.example.comMCP_URL_SEARCH は、名前とデータキーで Secret から読み取られるアドレス全体です。
MCP_HOST_SEARCH は、ツールが公開するホストです。dist/kubernetes/helm/ が保持するのはエージェントの Deployment とツールの Service だけです。Secret はレンダリングされず、キーを含むファイルはありません。
Docker Compose の場合
Compose にはシークレット参照がないため、compose の Release は同じスロットを
core/secret-value で埋め、その origin を Compose の変数参照にします。
release-compose.yaml より:
agent: uses: tools: search: features: endpoint: type: core/secret-value infra: origin: "${SEARCH_MCP_URL}"compose/dotenv-secret は参照を書かれたとおりに配信し、エージェントのサービスがそれを保持します。
dist/local/compose/docker-compose.yaml の agent サービスの environment(このファイルはこのサービスだけを定義します):
environment: MCP_HOST_SEARCH: mcp.example.com MCP_URL_SEARCH: ${SEARCH_MCP_URL}Docker Compose は、スタックの起動時に SEARCH_MCP_URL を置換します。値はシェル環境、--env-file で指定したファイル、またはプロジェクトディレクトリの .env ファイルから取得されます。そのため、ファイルには参照だけが含まれます。
エージェントの Recipes がスロットを読み取る仕組み
tools ソケット上の各接続は、その接続のエイリアスを大文字にした名前の環境変数になります。ツールが公開するホストからは MCP_HOST_<ALIAS> が、ツールが公開するアドレスからは MCP_URL_<ALIAS> が作られます。ただし、接続が endpoint シークレットを持つ場合は、MCP_URL_<ALIAS> はそのシークレットになり、公開されたアドレスは一切配信されません。credential を持つ接続には MCP_CREDENTIAL_<ALIAS> と、それを提示する際に使う、ツールが公開するリクエストヘッダーである MCP_CREDENTIAL_HEADER_<ALIAS> が追加されます。
- Kubernetes では、シークレットは接続とスロットを指定するアタッチメントエントリ(
connection: search、from: endpoint、as: env)であり、 プロバイダーがこれを上記のsecretKeyRefに変換します。その際、Secret の名前と データキーはhelm/k8s-existing-secretが公開する内容から読み取られます。 - Docker Compose では、シークレットは、それ自身のアタッチメントが配信したキー
values.keyの下で エージェントの inject パイプに届き、Recipe がその値を サービスの環境に書き込みます。
代わりにツールの infra.endpoint に書き込むと、キーは公開されたアドレスが届くところすべてに届きます。参照実装はアドレスを書かれたとおりに公開するため、エージェントの MCP_URL_SEARCH は、Kubernetes では Deployment に、Compose ファイルではサービスの環境に、キーをリテラル値として持つことになります。
制限
-
Docker Compose では、Release だけが 1 つのエージェントにアタッチする 2 つのシークレットが衝突します。 Release が行う各
core/secret-valueアタッチメントは Feature のデフォルトキーvalueの下で配信されるため、同じエージェントへの 2 つ目のアタッチメント(別のサーバーのアドレスや、これと並ぶ credential)があるとビルドが停止します。searchにendpointとcredentialの両方をアタッチする Release は、次のように出力します。[… 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.このキーは
valuesのリーフであり、それを書くのは Aggregate だけです。そのため、2 つのアタッチメントのうち 1 つを宣言してそのvalues.keyを指定する Aggregate は、この衝突を回避できます。エージェントの compose Recipe は、各シークレットをそれぞれのアタッチメントが指定するキーの下で読み取ります。Kubernetes にはこのような制限はありません。Kubernetes では各シークレットが、キーの下で配信される値ではなく、名前とデータキーによる Secret への参照だからです。 -
アドレスのパスに含まれるキー。 サーバーがキーをクエリ文字列ではなくパスから読み取る場合、ツールのアドレスはパスのその部分を取り除いたアドレスとなり、Secret がアドレス全体を保持します。
-
ホストは 2 回書かれます。ツールのアドレスに平文で、そして Secret の中にです。コンパイラは Secret を一切読まないため、両者が一致しているかどうかは何もチェックしません。
平文の変数内の $(VAR) 参照を使って、キーだけから実行時にアドレスを組み立てる方法は、Kubernetes でのみ機能します。Kubernetes はこのような参照を、コンテナ内でそれより前に列挙されたエントリから展開し、helm プロバイダは Secret から読み取るエントリを平文の変数より前に列挙します。一方、Docker Compose はサービスの環境エントリ間の $(VAR) 参照を一切展開しません。
応用する
- ヘッダーも検査するサーバー。 同じ接続に
credentialをアタッチします。エージェントはMCP_CREDENTIAL_SEARCHと、それを提示する際のヘッダーMCP_CREDENTIAL_HEADER_SEARCHを受け取ります。このヘッダーはAuthorizationですが、Release がツールのinfra.credential_headerでサーバー独自のヘッダーを指定した場合はそのヘッダーになります。 Docker Compose では、前述のとおり、2 つのうち一方のキーを Aggregate で指定します。 - 複数のサーバー。
toolsソケットにサーバーごとに 1 つの接続を配線します。 各接続の変数にはそのエイリアスが付き、各接続はそれぞれ独自の シークレットを保持します。 - ヘッダーからのみキーを読み取るサーバー。
endpointを省略すると、MCP_URL_<ALIAS>はツールが公開するアドレスになります。
決定性
両方の Releases は --verify-determinism のもとでビルドされます。このフラグはすべてのノードを 2 回レンダリングし、出力されたバイトを比較します。
aggrega build --release release-helm.yaml --verify-determinismどちらもクリーンなツリーから再ビルドすると、レンダリングされた出力がバイト単位で再現されます。
ファイル
aggregate.yaml— ツールとエージェントです。toolsソケットで接続され、 シークレットは付与されていません。manifest-helm.yaml、manifest-compose.yaml— ツールをmcp-remoteに、 エージェントを専用の Recipe に割り当て、各ターゲットが使用する認証情報の Feature を指定します。release-helm.yaml、release-compose.yaml— キーを含まないツールのアドレス、 エージェントのイメージ、およびエージェントの接続上のendpointシークレットです。catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml— エージェントです。credentialスロットとendpointスロットを持つtoolsソケットを定義します。catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml、catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml— 各ターゲットにおける エージェントです。.aggrega-config.yaml— カタログの検索スタックとレジストリです。build-release.sh— 1 つの Release をビルドし、同等のaggrega buildコマンドを表示します。
エージェントがヘッダーで提示するキーを、それが提示される接続上に保持する場合については、 connection-credentials を参照してください。両者の基盤となるモデルは Credential Model であり、 ツールの実現方法はツールのトランスポートラベルとともに AI Features で説明されています。