コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

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ここでの役割
searchcore/ai-tool/mcp他者が運用する Model Context Protocol サーバー。何も実行しない mcp-remote にマッピングされます
agentlocal/ai-agent/mcp-clientエージェント。tools ソケットを通じて search に接続されます

2 つの Releases が 1 つの Aggregate を共有し、それぞれが独自の Manifest を持ちます。

ReleaseManifestターゲットアドレス全体の取得元
release-helm.yamlmanifest-helm.yamlKubernetes名前空間がすでに保持している Secret:helm/k8s-existing-secret にバインドされた core/referenced-secret
release-compose.yamlmanifest-compose.yamlDocker ComposeCompose の変数参照:compose/dotenv-secret にバインドされた core/secret-value

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example mcp-address-from-secret

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd mcp-address-from-secret

ビルド

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

compose のビルドは 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/mcp

helm/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-address

Release は values を書かないため、origin は infra にあり、Secret から読み取るデータキーは Feature のデフォルトである value です。Manifest は core/referenced-secret を helm/k8s-existing-secret にバインドします。これは origin を名前空間がすでに保持している Secret の名前として読み取り、何もレンダリングしません。Secret は Release の外で、デプロイする側によって作成されます:

Terminal window
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.com

MCP_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.credential
    duplicate 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 回レンダリングし、出力されたバイトを比較します。

Terminal window
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 で説明されています。