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

MCP クライアント構成をインポートする

このウォークスルーでは、コーディングアシスタントに構成されている Model Context Protocol サーバー——コマンドラインから起動する 2 つと、他者が運用する 1 つ——をインポートし、Kubernetes 向けにサーバーをビルドします。これにより、クラスター内で動作するエージェントが同じツールにアクセスできるようになります。インポートは、ビルドが読み込むすべてのファイルを下書きします。各サーバーのコマンドラインまたはアドレス、それを実行する実現、そして GitHub サーバーのトークンの取得元です。以下のすべてのファイルと出力ブロックは実際の実行から得たものです。構成とウォークスルーの各段階は import-mcp サンプルにあり、そこではチェックスクリプトがインポートを再実行し、書き出した内容、表示した内容、このページが引用するブロックを、そこに保存されたファイルと比較し、インポートが書き出したものを検証してビルドします。

サンプルを生成する

このインポートは、このページのコマンドで実行することも、AI アシスタントに実行させることもできます。

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

Terminal window
aggrega scaffold --example import-mcp

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。それに続く以下のコマンドは、新しいフォルダーの source フォルダーに移動します。このフォルダーには、このページがインポートするものが入っており、インポートはここで実行します:

Terminal window
cd import-mcp

Visual Studio Code で開いた、スキャフォールドした例の source フォルダー。github、fetch、docs-search の 3 つのサーバーを持つ MCP 設定が表示されています。

構成

プロジェクトのルートにある、Claude Code の .mcp.json:

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"docs-search": {
"type": "http",
"url": "https://mcp.example.com/docs/mcp",
"headers": {
"Authorization": "Bearer ${DOCS_API_KEY}"
}
}
}
}

インポートは、Claude Desktop の claude_desktop_config.json、Cursor の .cursor/mcp.json、Visual Studio Code の .vscode/mcp.json、および MCP レジストリの server.json も同じ方法で読み込みます。構成の横にある .aggrega-config.yaml によって、このフォルダはワークスペースになります:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside .mcp.json.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

--target はカタログの Recipes から Manifest を下書きします。ワークスペースはカタログフォルダーを指定していないため、インポートはインポーターの取得元であるレジストリから標準ライブラリのカタログを読み込みます。これは公開されたカタログの署名付きスナップショットで、最初のインポートが取得・検証してワークスペースのコンテンツキャッシュに保持し、インポートが下書きの隣に書き込む記録の中でそのダイジェストによって示されます。AGGREGA_CATALOG_DIRS または workspace.catalog_dirs で独自のカタログフォルダーを指定しているワークスペースは、代わりにそれらに対してインポートします。

回答ファイル

Kubernetes では、GitHub サーバーはクラスターが保持する Secret からトークンを読み込みますが、どの MCP 構成もその Secret を指定していません。構成はシェルの GITHUB_TOKEN からトークンを読み込みます。そのため、インポートは Secret の名前を尋ねます。この例では、インポートが探す場所である .mcp.json の隣の import-answers.yaml に回答を保持しています:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.github.features.server_env.infra.origin: "github-mcp-token"

インポートは、回答なしで初めて実行されたときに、このファイルを自ら書き込みました。質問できるターミナルがなかったため、それ以外のすべてを下書きし、Secret の名前を空のままにし、そのキーをファイルに列挙して、次のメッセージで停止しました

1 value the drafts leave empty is still owed, listed in the answers file <workspace>/import-answers.yaml: write it beside its key there, then run the import again

ターミナルでは代わりに質問を行い、次回のインポートのために回答をファイルに書き込みます。回答は Secret の名前 github-mcp-token であり、トークンではありません。インポートの回答ファイルで、このファイルと質問を詳しく説明しています。

aggrega import には、別の場所に保存された回答ファイルを指定する --answers を含め、このコマンドが受け付けるすべてのフラグが記載されています。

source に移動します:

Terminal window
cd source

インポートを実行する

Terminal window
aggrega import .mcp.json --target helm

標準出力には書き出したものが一覧表示されます:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

標準エラーには次のように出力されます(<workspace> は実行したフォルダーを表します):

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the mcp format, with drafted paths relative to <workspace>
warn: the value of infra.stdio_command.0 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.2 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.0 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.stdio_command.1 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of headers.Authorization of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
warn: the value of infra.endpoint of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it empty
Pull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)

エディターから実行したインポート。下書きされた Aggregate、Release、Manifest が MCP 設定の横に表示され、Aggrega の出力には記述どおりに引き継がれた値と書き込まれたファイルが一覧表示され、通知にはインポートが 3 ファイルを下書きし、mcp として認識したことが示されています。

どのサーバーも標準ライブラリの MCP ツール core/ai-tool/mcp のインスタンスであるため、インポートは候補を評価せず、mapped 行も表示しません。

  • warn 行は、サーバーの構成が保持する値を示します。どの MCP クライアントもそれらを資格情報としてマークしませんが、どの値も資格情報を含みうるため——コマンドライン引数内のキーや、アドレス内のトークンなど——インポートは、含まれていたコマンドラインの各項目、各ヘッダー、各アドレスを、値ではなくサーバーと位置によって示します。下書きを共有する前にそれらを確認してください。env の値 ${GITHUB_TOKEN} は変数参照にすぎないため、それ自体の値を保持せず、どの警告もそれを挙げません。
  • Pull complete の行は、インポートが、ドラフトされた Release の依存先を aggrega pull と同じように release.lock へ取得していることを示します。これにより、ドラフトはすぐに検証とビルドができます。--offline の場合、インポートは何も取得せず、実行すべき aggrega pull を示します。

書き出される内容

Aggregate、Release、Manifest の名前は imported/mcp です。クライアントの設定には独自の名前がないため、ファイル名 .mcp.json から名前が付きます。レジストリの server.json には、その name から名前が付きます。名前空間は、インポーターの target_namespace 設定が定めるもので、別のものを設定しない限り imported です(設定)。

aggregate.yaml——サーバーごとに 1 つのインスタンスがあり、それらを使用するものはまだありません:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/mcp
version: 0.1.0
description: Draft Aggregate imported from a source in the mcp format.
spec:
components:
github:
type: core/ai-tool/mcp
fetch:
type: core/ai-tool/mcp
docs-search:
type: core/ai-tool/mcp

release.yaml——構成に記載されているとおりの、各サーバーの実行方法または到達方法と、GitHub サーバーのトークンの読み取り元となる Secret です:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/mcp
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the mcp format.
spec:
aggregate: imported/mcp
manifest: imported/mcp
components:
github:
infra:
stdio_command:
- "npx"
- "-y"
- "@modelcontextprotocol/server-github"
stdio_runtime: npm
features:
server_env:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN.
origin: "github-mcp-token"
fetch:
infra:
stdio_command:
- "uvx"
- "mcp-server-fetch"
stdio_runtime: pypi
# The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool:
# - Authorization: "Bearer ${DOCS_API_KEY}"
docs-search:
infra:
endpoint: "https://mcp.example.com/docs/mcp"
  • 環境 development は、どの構成も環境を指定していないためにインポートが書き込む既定値です。Release を別の場所にデプロイする場合は変更してください。
  • stdio_runtime は各コマンドから読み取られます。npx は npm パッケージを、uvx は PyPI パッケージを実行します。
  • GitHub トークン。サーバーの環境はその server_env スロットになります。Kubernetes では、core/referenced-secret-set の実現である helm/k8s-secret-set が、与えられた値をビルドがレンダリングする Secret に書き込むため、トークンがファイルに含まれてしまいます。そのため --target helm では、インポートは代わりに core/referenced-secret をアタッチし、クラスターがすでに保持している Secret——回答である github-mcp-token——を、変数ごとに 1 つのデータキー GITHUB_PERSONAL_ACCESS_TOKEN とともに指定します。ブリッジはその Secret のすべてのデータキーを同名の変数としてインポートするため、サーバーは手元のマシンと同じようにトークンを読み取り、レンダリングされたどのファイルにもトークンは含まれません。
  • Authorization ヘッダーはコメントのまま残ります。リモートサーバーの資格情報は、それを呼び出す側が、ツールへの自身の接続上で保持するものであり、このワークスペースにはまだ呼び出し側がありません。エージェントを docs-search に配線するときに、ヘッダーをその接続に設定します。

manifest.yaml——サーバーごとに名前で指定した 1 つの実現と、Secret の実現です:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/mcp
version: 0.1.0
spec:
mappings:
components:
type: {}
name:
github: helm/mcp-stdio-bridge
fetch: helm/mcp-stdio-bridge
docs-search: helm/mcp-remote
features:
type:
core/referenced-secret: helm/k8s-existing-secret

3 つの Kubernetes Recipes が core/ai-tool/mcp を実現します——1 つはイメージとして公開されたサーバー用、1 つはブリッジの背後で実行されるパッケージ用、1 つは他者が運用するサーバー用です——そして、どれが適合するかは各サーバーの性質であり、構成に記載されています。そのためインポートは各インスタンスを名前でマッピングします。コマンドラインから起動される github と fetch は、stdio ブリッジ helm/mcp-stdio-bridge の背後で実行されます。他者が運用する docs-search は helm/mcp-remote にマッピングされ、これは何も実行せずにアドレスを公開します。トークンの Secret は helm/k8s-existing-secret にマッピングされ、これは Secret を書き出すのではなく参照します。

release.lock は Release が解決されたカタログエンティティをダイジェストで記録し、.aggrega-import.json はインポートが書き出した内容の記録で、後の aggrega import --sync がこれを読み取ります。

Docker Compose の場合

サーバーは Docker Compose 上でも実行できます。aggrega import .mcp.json --target compose は github と fetch を compose/mcp-stdio-bridge に、docs-search を compose/mcp-remote にマッピングし、GitHub サーバーの環境を構成に書かれたとおりに保持します。つまり、値が変数参照 ${GITHUB_TOKEN} である core/referenced-secret-set のエントリで、compose/dotenv-secret-set によって実現されます。これはその参照を書かれたとおりにサービスの環境に書き込むため、スタックの起動時に Docker Compose がシェルから値を埋めます。このインポートは何も尋ねず、回答ファイル内の Secret の名前を使わずにそのまま保持します。

検証とビルド

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

検証後にエディターで開いた下書きの Release。Aggrega の出力と通知の両方が、問題は見つからなかったと報告しています。

下書きの Release のビルド。エクスプローラーに dist フォルダーが表示され、Aggrega の出力にはサーバーごとに Deployment と Service が一覧表示され、通知には 5 ファイルが書き込まれたことが示されています。

検証の出力は次のとおりです:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

そしてビルドは次のとおりです(<workspace> は実行したフォルダーを表します):

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: 5 files written to <workspace>/dist

notice 行は助言的なものです。Feature は origin を Aggregate の values または Release の infra から受け取り、この通知は 1 つのリーフが両方で宣言されていることを報告します。判定は何も変わりません。

ビルドは dist/helm/ の下に、ブリッジされた 2 つのサーバーそれぞれについて Deployment と Service を 1 つずつ、docs-search について Service を 1 つ書き出します。dist/helm/github-deployment.yaml 内の GitHub サーバーのコンテナは、サーバーのコマンドラインでブリッジを実行し、環境を Secret から取得します:

containers:
- name: main
image: ghcr.io/supercorp-ai/supergateway:4.1.0@sha256:1938c43538a5308bce07d58028e9de00b7acfecb40b39b059b2f3931800ad910
args:
- --stdio
- '''npx'' ''-y'' ''@modelcontextprotocol/server-github'''
- --outputTransport
- streamableHttp
- --stateful
- --port
- "8080"
- --streamableHttpPath
- /mcp
- --healthEndpoint
- /healthz
ports:
- name: http
containerPort: 8080
env:
- name: MCP_TOOL_SIDE_EFFECTS
value: mutating
- name: MCP_TOOL_TIMEOUT_SECONDS
value: "30"
- name: MCP_TOOL_PORT
value: "8080"
envFrom:
- secretRef:
name: github-mcp-token
[… omitted: the container's resources and its readiness probe]

dist/helm/docs-search-service.yaml は何も実行しません。他者が運用するサーバーに、クラスター内での名前を与えるだけです。

apiVersion: v1
kind: Service
metadata:
name: docs-search
[… omitted: the labels and annotations the build writes on every resource]
spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、自分ではフォルダーを作成しないでください。ワークスペースフォルダーにまだ `import-mcp` フォルダーがない場合は、`example` を `import-mcp` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これは新しい `import-mcp` フォルダーに例を書き込み、その `source` フォルダーにこのページがインポートするものが入ります。次に、`workspace_root` を `import-mcp/source`、`source` を `.mcp.json`、`target` を `helm` に設定して `import` ツールを呼び出してください。これは必要な回答を `.mcp.json` の横にある `import-answers.yaml` から読み取り、下書きを `import-mcp/source` に書き込み、それらに必要なものをプルします。次に、`workspace_root` を `import-mcp/source`、`release` を `release.yaml` に設定して `validate` ツールを呼び出し、`workspace_root` を `import-mcp/source`、`release` を `release.yaml`、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。それらは `import-mcp/source/dist/` の下にあります。

VS Code で開く

Visual Studio Code 用の Aggrega 拡張機能 をインストールしたら、インポートが下書きを書き込んだフォルダー import-mcp/source を VS Code で開きます。このフォルダーには Release が 1 つ、つまり下書きされた release.yaml があるため、エディターがそれを自動的に選択し、下書きを編集するたびにその Release に照らしてチェックし、見つかったものをファイル内と「問題」パネルに表示します。コマンドパレットの Aggrega: Show topology graph は、Release のコンポーネントとそれらの間の接続を描画します。Aggrega: Build、Aggrega: Preview build、Aggrega: Pull は同じ Release に対して動作し、それぞれアクティビティバーの Aggrega ビューにある Commands パネルのボタンとしても使えます。Build はフォルダーの dist/ にファイルを書き込みます。それ以外については Visual Studio Code で Aggrega を使う を参照してください。

実行する

ビルドは github-mcp-token Secret を書き出さないため、ファイルを適用する前に作成します。トークンを github-token.env に 1 行 GITHUB_PERSONAL_ACCESS_TOKEN=<your token> として書き込み、そこから Secret を作成します。これでクラスターがトークンを保持するので、ファイルは削除します:

Terminal window
kubectl create secret generic github-mcp-token --from-env-file=github-token.env
rm github-token.env
secret/github-mcp-token created

インポートの実行方法 の実行手順で説明しているとおりにビルドを適用し、2 つのサーバーを待ちます:

Terminal window
kubectl apply -R -f dist/helm/
kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5m
service/docs-search created
service/fetch-default created
deployment.apps/fetch created
service/github-default created
deployment.apps/github created
deployment.apps/fetch condition met
deployment.apps/github condition met

Docker Compose では、--target compose でインポートしてビルドしたワークスペースで、シェルの GITHUB_TOKEN にトークンを設定してスタックを起動します。Docker Compose はスタックの起動時にこれを読み取ります:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --wait

テストする

ブリッジは、MCP の Streamable HTTP トランスポートで、ポート 8080 の /mcp で各サーバーを提供します。MCP の initialize リクエストで fetch サーバーにセッションを開くよう求めます。このリクエストはトークンを読み取りません。

Docker Compose では、スタックのネットワーク mcp_compose 上の使い捨てコンテナから送信します。このネットワークでのサーバー名は fetch です:

Terminal window
docker run --rm --network mcp_compose curlimages/curl:8.11.1 -sS http://fetch:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
[… omitted: the same comment, repeated while the server starts]
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

Kubernetes では、ローカルポートをサーバーの Service fetch-default へフォワードし、コマンドは実行したままにします:

Terminal window
kubectl port-forward svc/fetch-default 8080:8080

別のターミナルから、転送したポートに同じリクエストを送ります。

Terminal window
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}'
: keepalive
: keepalive
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}

応答にはサーバー名 mcp-fetch が示されます。応答には時間がかかります。ブリッジはセッションごとにサーバーのコマンドライン uvx mcp-server-fetch を起動し、uvx はまずサーバーのパッケージをダウンロードしてインストールするためです。この実行では、Kubernetes で約 30 秒、Docker Compose で約 1 分かかりました。: keepalive 行は、その間にストリームが送るコメントです。

GitHub サーバーは、Docker Compose では http://github:8080/mcp で、Kubernetes では kubectl port-forward svc/github-default 8080:8080 を通じて、同じリクエストに応答します。initialize はトークンを読み取らないため、トークンの内容にかかわらず応答します。この実行ではプレースホルダーのトークンを使いました:

[… omitted: the keepalive comments, sent while npx installs the server]
event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-mcp-server","version":"0.6.2"}},"jsonrpc":"2.0","id":1}

ポートフォワードを停止してから、適用したものと Secret を削除します:

Terminal window
kubectl delete -R -f dist/helm/
kubectl delete secret github-mcp-token

Docker Compose では、スタックを停止して削除します:

Terminal window
docker compose -p mcp -f dist/compose/docker-compose.yaml down