agent-discover

agent-discover

セッション中に、あらゆる MCP ホストで MCP サーバーを検索、インストール、有効化できます。 agent-discover は、公式 MCP Registry、npm、PyPI を検索する単一のローカルデーモンです。正確なコマンドとその来歴を確認して承認するとサーバーをインストールし、設定の変更や再起動なしで、そのツールをホストに公開します。また、インストールしたものを保護します。ツール定義を固定し、ツールに変更があったサーバーを隔離します。シークレットは OS のキーチェーンに保管し、すべての操作を監査します。

---

理由

現在のホスト（Claude Code、Codex、Anthropic API、OpenAI API）にはそれぞれ独自のツール検索機能があるため、agent-discover の主な目的はもはやプロンプトトークンの節約ではありません。ホストのツール検索では、まだインストールしていないサーバーを扱えません。新しい MCP サーバーを追加するには、今でもホストの設定を編集してセッションを再起動する必要があります。agent-discover はその手順をなくします。

• 見つける。 1 回のクエリで、インストール済みサーバーのツールインデックスと公開レジストリ（公式 MCP Registry のローカルミラー、npm、PyPI）を検索します。
• 同意を得てインストールする。 install_server は正確なコマンドまたは URL、環境変数名とヘッダー名、固定されたバージョン、来歴の検証結果（レジストリの名前空間、npm の mcpName、PyPI、OCI ラベル）を表示します。承認するまで何も実行されません。
• 実行中に有効化・無効化する。 1 分前にインストールしたサーバーも対象です。有効化時に必要であれば、まずサーバーのインデックスを作成します。
• ホスト独自のツール検索に情報を渡す。 native モード（デフォルト）では、有効な各サーバーのツールが <server>__<tool> として一覧表示されます。変更のたびに agent-discover が notifications/tools/list_changed を送信するため、ホスト独自のツール検索、権限の確認、alwaysLoad の設定が引き続き機能します。proxy モードでは 8 つのメタツールのみが一覧表示され、すべて call_tool を経由します。ツール検索機能が弱い、または備わっていないホスト向けです。
• 制御を維持する。 信頼レイヤーをご覧ください。

	静的な MCP 設定	agent-discover を使用する場合
検出	事前にサーバー名を把握しておく	ニーズに応じて来歴を確認しながらレジストリを検索
インストール	設定を編集し、セッションを再起動する	1 回のツール呼び出しで、正確なコマンドを確認して承認する
有効化	設定済みのサーバーが常にすべて読み込まれる	セッション中に有効化・無効化でき、インデックスは検索可能なまま維持される
シークレット	設定ファイルまたは環境変数にキーを保存する	OS のキーチェーン（または暗号化ファイル）に保管し、接続時に注入する
ツールの変更	通知なし	ハッシュを固定し、ドリフトが検出されたサーバーは承認されるまで隔離する
可視性	ホストごとのログ	/discover ペイン、ヘルス状態、ツールごとのメトリクス、監査ログ、OTel

---

クイックスタート

Claude Code

プラグインをインストールします。MCP サーバーとして stdio シムを実行し、find と install のスキル、および管理 UI を備えた Claude Code モッド（関数フック）を追加します：

claude plugin marketplace add keshrath/agent-discover
claude plugin install agent-discover@agent-discover

ペインを初めて使いますか？チュートリアルでは、スクリーンショットを交えて使い方を説明しています。

• /discover を実行すると、エージェント検出ペインが開きます（フルスクリーンレイアウトではトランスクリプトの横にドッキングされ、それ以外ではプロンプトの上に表示されます。デスクトップ版の Code タブと VS Code でも利用できます）。キー 1〜4 でタブを切り替え、フォーカスは次のステップ（承認、有効化、検索フィールド、不足しているシークレット、インストール）に移動します。サーバー：インストール済みのすべてのサーバーとその状態を表示します。サーバーを開くと、設定（コマンドまたは URL、タグ、ソースとレジストリのステータス、パッケージ、環境変数とヘッダーのキー名のみ）、シークレットエディター（設定または削除。値は表示されません）、入力スキーマとツールごとのメトリクスを含むツール、ヘルスチェックとエラーのリセット、承認／無効のままにする操作ができる隔離差分、OAuth サインイン（認証 URL はリンクとして表示）、および有効化／無効化／再インデックス／アンインストールが表示されます。閲覧：レジストリを検索し、インストール計画（正確なコマンドまたは URL、来歴、警告、シークレット入力欄付きの必須キー）を確認して、インストールします。ログ（直近のプロキシ経由の呼び出し）と監査（サーバーと操作でフィルタリングし、ページ分けして表示）もあります。上流サーバーからの質問（エリシテーション）は一番上に表示されます。
• /discover <what you need> を実行すると、検索結果を表示した状態で「閲覧」が開きます。
• ステータス行には MCP 2/6 enabled · 1 to review（インストール済みのうち有効なサーバー数と、確認が必要なサーバー数）が表示されます。サーバーが隔離されたとき、正常でなくなったとき、または質問があるときはトーストが表示されます。また、対応が必要な項目があり、ペインが閉じている場合にのみ、プロンプトの上にバナーが表示されます。
• 各会話の開始時に、どのサーバーが有効かをモデルに伝え、機能が見つからないと言う前に search_tools を呼び出すよう指示するコンテキストブロックが追加されます。
• このモッドには Claude Code 2.1.289 以降が必要です。それより古いビルドでは、スキルとツールを引き続き利用できます。
• ツールが二重に表示されないよう、~/.claude.json に手書きで追加した agent-discover の項目は削除してください。

その他の MCP ホスト

{
  "mcpServers": {
    "agent-discover": { "command": "npx", "args": ["-y", "agent-discover@^3"] }
  }
}

Streamable HTTP に対応したホストでは、デーモンがすでに実行中の場合、代わりに http://127.0.0.1:3424/mcp を指定できます。Cursor、Codex、VS Code、Claude Desktop などについては、docs/SETUP.md を参照してください。

その他のホストでは、MCP ツール（Markdown 形式の結果。ホストがレンダリングする場合は MCP Apps ウィジェット）を介して agent-discover を利用します。隔離されたサーバーの承認や、エリシテーションに対応したクライアントなしでのインストールは、Claude Code の /discover ペインで行うか、オペレーターが AGENT_DISCOVER_ALLOW_UNCONFIRMED_INSTALL=1 を設定します。

ソースから

git clone https://github.com/keshrath/agent-discover.git
cd agent-discover
npm install
npm run build
node dist/index.js daemon

---

実行の仕組み

各マシンで 1 つのデーモン agent-discover daemon が 127.0.0.1:3424 をリッスンし、REST API（/api/*。Claude Code のペインが使用）と、/mcp の MCP Streamable HTTP を提供します。/mcp は同じエンドポイントで、2026-07-28 プロトコルと 2025 セッション対応プロトコルを処理します。

デフォルトのバイナリ agent-discover は、薄い stdio シムです。/api/health を確認し、デーモンが実行されていなければ起動して（ロックファイルで保護され、デタッチされます）、stdio を /mcp に中継します。すべてのホストとすべてのセッションで同じデーモンを共有するため、接続状態と有効化状態の管理者は 1 つに統一されます。開いている HTTP 通信が 30 分間ない場合、デーモンは終了します（AGENT_DISCOVER_IDLE_MS）。

詳細：docs/ARCHITECTURE.md。

---

MCP ツール（8）

ツール	目的
search_servers	インストール済みサーバーに加え、まだインストールしていないサーバーを探すための公開レジストリ／npm／PyPI の候補を検索します。
install_server	レジストリ、npm、PyPI の正確な名前（バージョン固定）、または手動コマンドや URL を指定してインストールします。計画の確認を求めた後、インデックスを作成します。
enable_server	サーバーのツールをホストに公開します。隔離中のサーバーについては、差分を確認して再承認するよう求められます。
disable_server	ツールの公開を停止します。サーバーはインストール済みで検索可能な状態のままです。
server_status	インストール済み／インデックス作成済み／有効／接続済み／隔離中の状態、ツール数、フラグ付きツール、ヘルス状態を表示します（check_health はライブプローブを実行します）。
search_tools	インストール済みサーバーすべてのツールインデックスを対象に、最大10件のクエリをまとめて検索します。有効かどうかは問いません。
get_tool	サーバー名とツール名を指定して、インデックス作成済みツールの完全な定義を取得します。
call_tool	インデックス作成済みの任意のツールを呼び出し、上流の結果を変更せずに返します。proxy モードでツールを呼び出す方法です。

プロンプト discover、install、status は、MCP プロンプトを表示するホストではスラッシュコマンドとして表示されます。call_tool を除くすべてのツールは outputSchema を宣言し、structuredContent と Markdown 形式のレンダリングを返します。

MCP Apps ウィジェット。 ツールの結果には ui://agent-discover/app.html が含まれます。これは検索結果、サーバーカード、インストールの同意画面、ツールテスターを表示する単一のウィジェットです。Claude Desktop、claude.ai、VS Code では表示されます。Claude Code はまだ MCP Apps を表示しないため、代わりに Markdown を表示します。

完全なスキーマ：docs/API.md。

---

信頼レイヤー

agent-discover は、作成元ではない MCP サーバーとホストの間に位置するため、サーバーの説明を悪意のあるものとして扱います。モデルの詳細：docs/SECURITY.md。

• 出所情報付きのインストール同意。 計画には、正確なコマンド、固定されたバージョン、レジストリの名前空間／パッケージのメタデータ確認が表示されます。エージェントが指定する confirm 引数は意図的に用意していません。
• ツールの固定と隔離。 サーバーの最初のインデックス作成時に、各ツールの説明、入力スキーマ、アノテーションのハッシュを固定します。その後に変更、追加、削除があった場合、読みやすい差分を確認して再承認するか（またはツールが元に戻るまで）、サーバーを隔離します。
• 説明の衛生管理。 制御文字、ゼロ幅文字、双方向テキスト制御文字を削除し、説明の長さに上限を設け、プロンプトインジェクションの可能性を示す6種類のヒューリスティックでフラグを付けます。フラグは注意喚起であり、制御手段は固定です。
• シークレットは OS のキーチェーンに保存します。キーチェーンを利用できない場合は AES-256-GCM でファイルに保存します。SQLite には保存せず、マスクされていない状態で一覧表示することもありません。
• 監査ログは追記専用で、GET /api/audit から読み取れます。
• OpenTelemetry は OTEL_EXPORTER_OTLP_ENDPOINT または AGENT_DISCOVER_OTEL=1 でオプトインできます。
• ループバックのみ。 ホスト／Origin の許可リスト、JSON 専用のリクエスト本文、状態を変更するすべての REST 呼び出しに対する起動ごとのトークンを使用します。
• リモートサーバー向け OAuth 2.1（検出、PKCE、更新、iss チェック）に対応し、サインインは URL としてユーザーに引き渡されます。agent-discover 自体が URL を開くことはありません。

対象外：上流の stdio サーバーのサンドボックス化。これらのサーバーはユーザーの権限で実行されます。

---

検索品質

search_tools は、SQLite FTS5（Porter ステミング、名前・説明・引数名を対象としたフィールド指定の BM25）、誤字修正、サーバールーティング、少量の使用頻度に基づく事前情報を使ってランキングします。ローカルまたは OpenAI の埋め込みプロバイダーはオプトインで利用でき、密ベクトルスコアを追加します。

bench/retrieval/ の検索ベンチマークで測定しています。対象は実際の MCP サーバー 50 台、ツール 1674 個、手作業でラベル付けしたクエリ 468 件（言い換え、タスク、サーバー横断、複数ステップ、誤字、ドイツ語、回答不能）です。チューニングにはすべて開発用分割データを使用しました。以下の数値は、保留したテスト用分割データ（回答可能なクエリ 269 件）の結果です。

ランカー	R@1	R@5	R@10	MRR
プレーンな BM25（ホスト型 BM25 ツール検索におおむね相当）	0.305	0.522	0.618	0.430
agent-discover 1.x	0.307	0.561	0.642	0.446
agent-discover 2.0、設定不要	0.338	0.576	0.661	0.474
2.0 + multilingual-e5-small（オプトイン）	0.381	0.618	0.722	0.522

この結果は正直に受け止めてください。

• プレーンな BM25 に対する設定不要の改善幅はわずかです（R@10 で 4 ポイント増）。密ベクトル方式ではさらに約 6 ポイント増えます。
• これは検索のみを評価するものです。ツールを選ぶ LLM は使用しておらず、コーパスには実際の説明文にばらつきがある公開サーバーを使っています。
• e5 の行を再現するには、npm install @huggingface/transformers を手動で実行する必要があります（モデルは約 130 MB、ツール 1674 個のインデックス作成には 1 スレッドで約 3 分かかります）。CI では実行されません。
• ツールごとに 5 件のクエリを使って LLM で説明文を拡充すると、オフラインで R@10 は 0.922 に達しましたが、これはベンチマーク専用であり、製品には含まれていません。インデックス作成時に LLM が必要であり、ラベル付けされたクエリも LLM が作成したものなので、上限値として扱ってください。
• スコアの下限は適用していません。回答不能なクエリと回答可能なクエリを区別するシグナルがなかったため、2.0 は検索を拒否するふりをせず、最良の一致結果を返します。

手法、カテゴリ別の結果、実行方法については、bench/retrieval/README.md を参照してください。CI では npm run bench:retrieval -- --check を実行します。

---

機能

• SQLite のローカルレジストリ：サーバー、インデックス化されたツール、サーバーごとのシークレット、メトリクスを管理します。有効化とは独立してインデックスを作成します。インストール時にサーバーを一度プローブし、ツールを保存して切断します。
• 公式 MCP Registry（v0.1 API）のレジストリミラー：updated_since による差分同期、非推奨および削除ステータスの追跡、名前の完全一致によるインストールに対応します。レジストリのエントリーが削除されたサーバーには、server_status でフラグが付けられます。
• レジストリミラー、npm、PyPI を対象としたフェデレーション検索。
• 上流サーバーへのトランスポート：stdio、SSE、ストリーミング可能な HTTP に対応し、両方のプロトコル世代を自動でネゴシエーションします。上流からの input_required および 2025 年の elicitation/create リクエストをクライアントに中継します。
• 再接続時のバックオフ、アイドル時の切断、実際のヘルスプローブを備えた遅延接続と接続プール。
• 3 つの UI：Claude Code の /discover ペイン、MCP Apps ウィジェット（Claude Desktop、claude.ai、VS Code）、その他すべてのホスト（OpenCode、Cursor、Codex など）向けの Markdown 形式の結果。3.0 以降、Web ダッシュボードはありません。
• デーモン起動時にインストールを保証するサーバーを指定する宣言型セットアップファイル（AGENT_DISCOVER_SETUP_FILE）。
• ツールごとのメトリクスと呼び出しログ。

---

環境変数

主な環境変数です。全一覧はdocs/API.mdをご覧ください。

変数	デフォルト	説明
AGENT_DISCOVER_PORT	3424	デーモンのポート
AGENT_DISCOVER_HOST	127.0.0.1	リッスンアドレス
AGENT_DISCOVER_DATA_DIR	プラットフォームのデータディレクトリ	データディレクトリ（「1.x からのアップグレード」を参照）
AGENT_DISCOVER_DB	その中の agent-discover.db	SQLite ファイルのパス
AGENT_DISCOVER_MODE	native	native は有効なサーバーのツールを一覧表示し、proxy はメタツールのみを一覧表示します
AGENT_DISCOVER_IDLE_MS	1800000	デーモンのアイドル終了時間（0 = 終了しません）
AGENT_DISCOVER_SETUP_FILE	未設定	起動時に同期する宣言型サーバー一覧
AGENT_DISCOVER_EMBEDDING_PROVIDER	none	local または openai を指定すると、セマンティックランキングが追加されます
AGENT_DISCOVER_SECRETS	自動	keyring または file を指定すると、シークレットバックエンドを固定します

---

アップグレード

2.x からのアップグレード： 3.0 では、ポート 3424 のウェブダッシュボード（WebSocket、テスター、プリセット、一時サーバー用ルートを含む）と agent-desk のサポートが削除されました。Claude Code では /discover でサーバーを管理できます。他のホストでは引き続き MCP ツールを利用できます。ホスト設定は agent-discover@^3 に移行します。詳細はCHANGELOG.mdをご覧ください。

1.x からのアップグレード： 2.0 は破壊的変更を伴うリリースです。単一の registry ツールは上記の 8 つのツールに置き換えられ、REST ルートの名前が変更され、セットアップファイルのキー auto_activate は enabled になり、シークレットはキーチェーンに移行し、デフォルトのバイナリは shim になります。データベースは自動的に移行され、初回起動時に ~/.claude からユーザーごとのデータディレクトリ（%LOCALAPPDATA%\agent-discover、~/Library/Application Support/agent-discover、または $XDG_DATA_HOME/agent-discover / ~/.local/share/agent-discover。AGENT_DISCOVER_DATA_DIR で上書き可能）に移動します。そのため、先に実行中の 1.x プロセスを停止してください。全項目はCHANGELOG.mdをご覧ください。

---

既知の制限事項

• Claude Code は、ツールの structuredContent を Markdown の content ではなく JSON テキストとしてモデルに転送します（上流の動作。anthropics/claude-code#55677 は対応予定なしとしてクローズ。あわせて #15412 も参照してください）。他のホストとウィジェットでは Markdown / UI が使用されます。
• stdio サーバー向けの Docker サンドボックス化はまだ含まれていません（延期）。

---

テスト

npm test              # 218 tests across 27 files (+9 e2e skipped unless AGENT_DISCOVER_E2E=1, +16 pane e2e)
npm run check         # typecheck + lint + format + test
npm run bench:retrieval
npm run plugin:check  # claude plugin validate + the pane's 9 plugin tests
npm run e2e:claude    # the /discover pane in the real Claude Code CLI (inline and docked), screenshots to ~/.claude/tmp/pane-shots

---

ドキュメント

• チュートリアル：スクリーンショット付きで、/discover ペインの使い方を手順ごとに説明します
• ユーザーマニュアル：日常的な使い方
• セットアップガイド：インストールとクライアントごとの設定
• API リファレンス：MCP ツール、REST、環境
• アーキテクチャ：プロセスモデル、ドメインサービス、スキーマ、検索
• セキュリティ：信頼モデル
• 変更履歴

---

ライセンス

MIT。LICENSEをご覧ください。