MCP サーバーの接続
Aggrega の MCP サーバーは aggrega mcp コマンドであり、前提条件は aggrega バイナリだけです。バイナリのインストールでは、1 つのコマンドでバイナリをインストールできます。サーバーはクライアントのサブプロセスとして stdio 経由で動作し、スキーマはバイナリから、ドキュメントページはマシンのキャッシュに一度だけ取得したコピーから読み込むため、別途サービス、ポート、アカウントを用意する必要はありません。すでに他の誰かがサーバーを運用している場合は、バイナリもここに書かれた手順も不要です。HTTPS 経由で接続するサーバーを参照してください。
1 つのコマンドで追加できるクライアント
Aggrega プラグインをインストールしたアシスタントは、すでに接続されています。プラグインをインストールすると、Aggrega スキルとサーバーが 1 つの手順で追加されます(Claude Code、Codex、GitHub Copilot、Gemini CLI、Antigravity、Cursor、Kiro、OpenClaw が対象で、プラグインのインストールで説明しています)。そのため、そのアシスタントを接続するためにこのページの他の手順は必要ありません。プラグインは、アシスタントの起動時の PATH で見つかった aggrega を使って aggrega mcp を起動するため、バイナリはそこにインストールされている必要があります。一部のアシスタントは、プラグインのサーバーをプロジェクトではなくプラグイン自身のフォルダーで起動します(Codex がそうです)。その場合、アシスタントはそれを受け付ける呼び出しで、プロジェクトのフォルダーを workspace_root として指定します。スキルは、サーバーがどのワークスペースで応答するかを確認するようアシスタントに指示します。
プラグインを使わない場合は、クライアント独自のコマンドでサーバーを追加します。Claude Code の場合:
claude mcp add --transport stdio aggrega -- aggrega mcpCodex では:
codex mcp add aggrega -- aggrega mcpGemini CLI では:
gemini mcp add aggrega aggrega mcpその他のすべてのクライアント
MCP に対応したほとんどのクライアントは、同じ方法でサーバーを起動します。aggrega コマンドを単一の mcp 引数付きで実行し、プロセスの標準入力と標準出力でプロトコルをやり取りします。クライアントごとに異なるのは、サーバーリストをどこに保持するか、そしてその中のエントリーを何と呼ぶかです。共通の形は次のとおりです。
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}クライアントが再起動して接続すると、Aggrega のオーサリング用のプロンプト、リソース、ツールが利用可能になります。それらについてはアシスタントが Aggrega でできることで説明し、使い方は Aggrega ファイルのオーサリングで示し、コマンド自体については aggrega mcp のリファレンスで扱っています。
エントリーにはプロトコルのリビジョンを選択する項目はありません。 Aggrega は標準入出力でも HTTPS 経由でも 2026-07-28 と 2025-06-18 の両方を話すため、どちらのクライアントも接続でき、同じプロンプト、リソース、ツールに到達します。クライアントがどちらを要求するかは、設定ではなく通信上で決まります。
コマンドを実行できるアシスタントなら、これらすべてを自分で行えます。バイナリのインストール、Aggrega スキルの追加、サーバーへの接続を、貼り付ける 1 つのプロンプトから行います。AI アシスタントで Aggrega をセットアップするを参照してください。
各クライアントがサーバーリストを保持する場所
| クライアント | リストの場所 | エントリーの呼び名 |
|---|---|---|
| Claude Code | claude mcp add、またはプロジェクト内の .mcp.json ファイル | mcpServers |
| Claude Desktop | ローカルサーバーの場合は拡張機能の設定、HTTPS 経由で接続するサーバーの場合はコネクタの設定 | Claude Desktop を参照 |
| Cursor | 1 つのワークスペース用には .cursor/mcp.json、すべてのワークスペース用にはユーザースコープの mcp.json | mcpServers |
| Gemini CLI | gemini mcp add、またはすべてのプロジェクト用の ~/.gemini/settings.json と 1 つのプロジェクト用の .gemini/settings.json | mcpServers |
| Codex CLI | codex mcp add、またはすべてのプロジェクト用の ~/.codex/config.toml と信頼済みの 1 つのプロジェクト用の .codex/config.toml | [mcp_servers.aggrega] テーブル — Codex CLI を参照 |
| Zed | Settings → AI → MCP Servers(エントリーを Zed の設定ファイルに書き込みます) | context_servers — Zed を参照 |
| Visual Studio Code | ユーザープロファイル内の mcp.json、または 1 つのワークスペース用の .vscode/mcp.json | servers(Visual Studio Code を参照) |
| GitHub Copilot CLI | copilot mcp add、またはホームディレクトリに保持される mcp-config.json ファイル | mcpServers |
| Antigravity | 設定から開ける mcp_config.json ファイル | mcpServers |
| Windsurf | 設定から開ける mcp_config.json ファイル | mcpServers |
| Cline | MCP 設定(cline_mcp_settings.json ファイルに保存) | mcpServers |
この表のクライアントのうち、以下で個別のセクションがある 4 つを除くすべてが、上記のエントリーをそのまま、各行に示すパスで受け付けます。表にないクライアントも、これらのいずれかの形のサーバーリストを読み込むものであれば同じ方法で接続できます。
PATH に関する注意
グラフィカル環境から起動されたクライアントは、ターミナルと同じ PATH を継承するとは限りません。クライアントが aggrega コマンドを見つけられないと報告する場合は、"command": "aggrega" をバイナリの絶対パスに置き換えてください(例: "command": "/home/you/.local/bin/aggrega"。これは Linux で you という名前のユーザーのインストール先です)。それ以外はすべて同じです。
Visual Studio Code
Visual Studio Code はサーバーを mcpServers ではなく servers の下に保持し、各エントリーは使用するトランスポートを指定します。
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex はサーバーを JSON ではなく TOML で保持します。すべてのプロジェクト用には ~/.codex/config.toml に、Codex が信頼する 1 つのプロジェクト用には .codex/config.toml に、それぞれサーバー名を付けたテーブルとして記述します。
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp(前述のコマンド)を実行すると、同じテーブルが書き込まれます。Codex IDE 拡張機能と ChatGPT デスクトップアプリも同じファイルを読み込むため、1 つのエントリーで 3 つすべてに対応できます。
Zed
Zed はサーバーを設定ファイルの context_servers の下に保持します。Settings → AI → MCP Servers から Add Server、続いて Add Local Server を選んでサーバーを追加すると、エントリーがそのファイルに書き込まれます。または、コマンドパレットから zed: open settings file を実行して、エントリーを自分で追加します。
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed はプロトコルのツールとプロンプトに対応しているため、Zed のエージェントは Aggrega のツールとオーサリングプロンプトを利用できますが、サーバーが提供するリソースは利用できません。
Claude Desktop
Claude Desktop は、設定ファイルのエントリからではなく、拡張機能パッケージからローカルサーバーをインストールします。拡張機能パッケージとは、サーバーとそれを記述する manifest を 1 つのインストール可能なファイルにまとめたもので、拡張機能の設定から追加します。Aggrega の各 release には、ビルド済みバイナリと並んでそのようなパッケージ aggrega-<version>.mcpb が含まれています。
Aggrega のパッケージは、独自のプログラムを含みません。マシンにすでにインストールされている aggrega 実行ファイルを単一の mcp 引数で起動し、そのプロセスの標準入出力でプロトコルを話します。これは上記の各エントリが起動するのと同じサーバーです。別の実行ファイルを選択しない限り、上記の各エントリと同様にコマンド名 aggrega を Claude Desktop に渡すため、アプリケーションは自身の起動時の PATH 上で aggrega を探します。また、選択したワークスペースをそのサーバーに渡します。追加するには、次の手順に従います。
- バイナリのインストールの説明に従って
aggregaバイナリをインストールします。そこで説明しているインストールコマンドと手動の手順はどちらも、管理者権限なしで置き換えられるよう、C:\Windows\System32のようなシステムフォルダーではなく、自分専用のフォルダー(Windows では%LOCALAPPDATA%\Programs\aggrega)に置きます。 - Claude Desktop の拡張機能の設定から
aggrega-<version>.mcpbをインストールします。 - パッケージの設定を行います。どちらも必須ではありません。Path to the aggrega executable はパッケージが起動するプログラムで、既定値はコマンド名
aggregaです。アプリケーションはこれを自身の起動時のPATH上で探します。アプリケーションの実行中にPATHに追加されたフォルダー(Windows インストーラーと Windows のインストールコマンドはそれぞれのフォルダーを追加します)は、手順 4 のようにアプリケーションを終了して再起動するまで反映されません。また、グラフィカル環境から起動したアプリケーションには、ターミナルと同じPATHが見えない場合があります(PATHに関する注意を参照)。そのPATH上のaggregaが目的の実行ファイルである場合は、既定値のままにします。目的の実行ファイルがそのPATH上にない場合や、そこで最初に見つかるaggregaとは別のものである場合は、代わりにフィールドに実行ファイルのフルパスを設定します。macOS と Linux では、インストール先としてホームフォルダーの.local/binにあるaggrega(例:/Users/you/.local/bin/aggrega)、Windows ではaggrega.exeで終わるフルパス(例:C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe)です。既定値に戻すには、フィールドを空にするのではなくaggregaに設定します。aggregaがまったくインストールされていない場合は、手順 1 の説明に従ってインストールします。Workspace folder はアシスタントが作業する Aggrega ワークスペースのフォルダー、つまりプロジェクトの.aggrega-config.yamlを含むフォルダーです。こちらは設定してください。フォルダーを選択するまでは空であり、空の間はパッケージがサーバーに空のAGGREGA_WORKSPACE_ROOTを渡すため、サーバーは、Claude Desktop が起動したフォルダーで作業するのではなく、アシスタントがワークスペースで行うすべてのリクエストに対して、Workspace folder 設定が空であることを伝え、ワークスペースの.aggrega-config.yamlを含むフォルダーに設定するよう求める拒否を返します。パッケージがフォルダーをサーバーに渡すのはアプリケーションがサーバーを起動するときだけです。そのため、サーバーの実行中に設定したフォルダーは、拡張機能の設定で拡張機能をオフにしてから再度オンにするか、手順 4 のようにアプリケーションを再起動した後に有効になります。 - Claude Desktop を完全に終了してから、再度起動します。アプリケーションがすでに起動したサーバーは実行を続け、実行ファイルの名前を変更しても停止しないため、変更した設定は、アプリケーションがサーバーを再度起動した後、つまりアプリケーションを終了して再起動した後、または Workspace folder については拡張機能をオフにしてから再度オンにした後にのみ有効になります。Windows では、タスク マネージャーで
aggregaプロセスがまだ実行中かどうかを確認できます。
ワークスペースフォルダーは、独自のワークスペースを指定しないすべてのリクエストが処理される場所です。 Claude Desktop はプロジェクト内ではなく自ら選んだフォルダーでサーバーを起動するため、パッケージは選択されたフォルダーを、アプリケーションが組み立てるコマンドラインの引数としてではなく、環境内の AGGREGA_WORKSPACE_ROOT 変数としてサーバーに渡します。サーバーは、すべてのコマンドで --workspace-root が扱われるのと同様に、そのフォルダー自体をワークスペースルートとして扱います。その上位で包含するワークスペースを探すことはないため、.aggrega-config.yaml の内側のフォルダーではなく、それを含むフォルダーを選択してください。別のワークスペースで作業するには、設定を変更し、手順 4 のとおりにアプリケーションを再起動します。相対パスの workspace_root で独自のワークスペースを指定するリクエストでも、そのパスはワークスペースフォルダーを基準に解釈されます。そのため、プロンプトはフォルダーがマシン上のどこにあるかを知らなくても、その中のフォルダー(例: quickstart-ai/1)を指定できます。絶対パスの workspace_root は指定どおりに使われます。設定が空の間は、相対パスのものにも、ワークスペースを指定しないリクエストと同じ拒否が返されます。
パッケージはどのプラットフォームの実行ファイルも指定しないため、同じファイルが宣言されたすべてのプラットフォーム(macOS、Windows、Linux)に適用されます。
サーバーは、パッケージがどの aggrega を起動したかを報告します。 Claude Desktop の拡張機能の設定には、パッケージ自身のバージョン(取得元の release のバージョン)が表示され、パッケージが起動する実行ファイルのバージョンは表示されません。両者は別々にインストールされるため、異なる release のものである場合があります。パッケージは環境内の AGGREGA_BUNDLE_VERSION 変数として自身のバージョンをサーバーに渡し、サーバーは両方を報告します。引数なしで呼び出した describe-capabilities(サーバーが提供するものを知るためにアシスタントが呼び出すツール)の応答は、実行ファイルのバージョンとパッケージのバージョンを示す行で始まり、構造化部分にも同じ行を version_summary として含みます。そのため、どの Aggrega のバージョンが実行中かを尋ねられたアシスタントは、アプリケーションが応答のどの部分を渡しても、そこで両方を読み取れます。両者が異なる release のものである場合、その行はその旨を両方の名前とともに示し、接続時にサーバーがアシスタントに渡すガイダンスも同じ文で始まります。違いがあっても何も拒否されず、サーバーはすべてのリクエストに通常どおり応答します。これは、パッケージがどの実行ファイルを実行しているかを把握できるように報告されるものです。両者を揃えるには、実行ファイルの取得元の release の aggrega-<version>.mcpb をインストールするか(そのバージョンはターミナルで aggrega version を実行すると表示されます)、Path to the aggrega executable にパッケージの release の aggrega のフルパスを設定してから、手順 4 のとおりにアプリケーションを再起動します。
Claude Desktop 自身のログに、起動したものが表示されます。 Windows では、Claude Desktop を独自のダウンロードからインストールした場合でも、ログは %APPDATA%\Claude\logs ではなく、ローカルのアプリケーションデータディレクトリ内のパッケージフォルダーの下にあることがあります。具体的には %LOCALAPPDATA%\Packages\ の下の、名前が Claude_ で始まるフォルダー内の LocalCache\Local\Claude\logs です。そこにあるファイルには mcp.log と mcp-server-Aggrega.log が含まれ、後者には Aggrega サーバーが標準エラーに書き込む内容が記録されます。Using MCP server command: を含む行は、アプリケーションが起動したコマンドを示します。このコマンドはパッケージの Path to the aggrega executable 設定から取得されます。設定が何も存在しないパスを指している場合、ログにはそのパスがコマンドとして認識されないという Windows コマンドインタープリターのメッセージが記録され、続いてサーバーを起動できなかったことが報告されます。ワークスペースフォルダーが存在しない場合(名前の変更、移動、または未作成)、サーバーはそれでも起動し、アシスタントがそのワークスペースで行うすべてのリクエストに拒否を返します。そのため、アプリケーションが接続の失敗を報告するのではなく、アシスタントがリクエストへの応答として拒否を受け取ります。この拒否は、パッケージの Workspace folder 設定が設定する変数として AGGREGA_WORKSPACE_ROOT を示し、アプリケーションが渡したとおりにフォルダーを引用します。mcp-server-Aggrega.log にも同じ拒否が記録されます。Workspace folder が空のままの場合も同様に、空の設定を示す手順 3 の拒否が返され、ログにも記録されます。設定を修正し、手順 4 のとおりにアプリケーションを再起動してください。
Claude Desktop のコネクタ設定は、HTTPS 経由で到達するサーバー向けのもう 1 つの方法です。HTTPS 経由で到達するサーバーを参照してください。
クライアントがツール全体を受け付けない場合
Aggrega はツール全体を公開し、そのうちどれだけをモデルに提示するかはクライアントの判断に委ねます。一部のクライアントは一度に登録するツールの数に上限を設け、残りを破棄します。その場合、mcp.announce_tools を使うと、サーバーが公開するツールを指定したものに絞り込めます。サーバーが公開するものの絞り込みを参照してください。
HTTPS 経由で接続するサーバー
上記のエントリはいずれも、サーバーを自ら起動します。他の誰かが運用するサーバー(ホスト上で 1 つのワークスペースを提供する、長時間稼働する 1 つのプロセス)には、代わりにネットワーク経由で接続し、そのエントリにはコマンドではなくアドレスを指定します。
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}パスは常に /mcp です。ホストは、運用者がそのサーバー用に公開したものです。運用者に問い合わせてください。Gemini CLI はアドレスを url ではなく httpUrl で受け取ります。Gemini CLI は url を旧来のイベントストリーム・トランスポートのサーバーとして、httpUrl をこのサーバーが使う Streamable HTTP トランスポートのサーバーとして読み込みます。
トークンを取得するのはユーザーではなくクライアントです。 サインインに関する設定はエントリには一切ありません。サーバーは認証されていないリクエストに対して、どの認可サーバーがトークンを発行するかを示すドキュメントを提示して応答します。プロトコルの認可フローに対応したクライアントはそのドキュメントを読み、ユーザーをサインインに誘導し、受け取ったトークンを以降のすべてのリクエストに付加します。クライアントが要求できるスコープ名も、同じドキュメントで公開されています。このフローを実装していないクライアントはこの種のサーバーに接続できず、エントリに何を追加してもその代わりにはなりません。
サインインのスコープが届かないツールも、ツール一覧には表示されます。 そのツールの呼び出しは拒否され、拒否にはそれを許可するスコープが示されます。プロトコルのステップアップを実装したクライアントは、その拒否に応じて、そのスコープのために再度サインインするよう求めます。ステップアップを行わないクライアントにも書き込みスコープを与えることはできます。認可サーバーの運用者がそれらをそのクライアントのデフォルトスコープにすれば、最初のサインインで既にそれらが付与されます。ただしその代償として、そのクライアントを通じたすべてのサインインが書き込み権限を持つことになります。各スコープが何を許可するか、また接続のたびに新たに自身を登録するクライアントに対してその設定がどう振る舞うかは、呼び出し元が到達できる範囲で説明しています。
このようなサーバーの要件と、運用者が設定する内容については、aggrega mcp リファレンスを参照してください。
接続を確認する
クライアントが再接続したら、連携が有効になっていることを確認します。クライアントには Aggrega のオーサリングプロンプト(開発者、アーキテクト、運用の各ロールに 1 つずつと、エンティティごとのテンプレート)と、scaffold、validate、describe、get-schema を含むオーサリングツールが一覧表示されるはずです。アシスタントに component のスキャフォールドを依頼すると、Component に必須のフィールドを備えたスケルトンが返されるはずです。何も表示されない場合は、ターミナルから aggrega version が実行できること、およびクライアントの command がバイナリに解決されることを確認してください。よくある原因については、上記の PATH に関する注記で説明しています。