pi-mcp-adapter: MCP のツール定義を 1 つのプロキシツールに畳む

このアダプターが削っているのは何のコストか

MCP サーバーを 1 つ繋ぐと、そのサーバーが公開するツール定義がまとめてコンテキストに載る。README はこの点を「A single MCP server can burn 10k+ tokens」と表現し、使うかどうかに関係なくそのコストを払うことになると説明している。数個のサーバーを繋げば会話を始める前にコンテキストの半分が埋まる、というのが README の主張だ。

pi-mcp-adapter はこの構造を変える。数百のツール定義を展開する代わりに、約 200 トークンのプロキシツールを 1 つだけ置く。エージェントは必要なときに検索し、必要なツールだけを取り出す。README の表現では「One proxy tool (~200 tokens) instead of hundreds」。対象読者は Pi をコーディングエージェントとして使い、かつ MCP サーバー資産（データベース、ブラウザ、API）を手放したくない人である。

README は Mario Zechner の「why you might not need MCP」という記事に触れ、そこでの結論（MCP を捨てて単純な CLI ツールを書けばよい）を紹介したうえで、それとは別の道を提示する位置づけを取っている。MCP を否定するのではなく、定義の常時展開という部分だけを外す。

プロキシツール経由の探索と実行、そして遅延接続

エージェントが最初に使うのは mcp という単一のツールである。README の例では mcp({ search: "screenshot" }) を呼ぶと、候補として chrome_devtools_take_screenshot が説明文とパラメータ一覧つきで返る。パラメータには format（enum: "png" | "jpeg" | "webp"、既定 "png"）や fullPage（boolean）が含まれる。次に mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } }) を呼ぶと実際の実行に進む。README はこれを「Two calls instead of 26 tools cluttering the context」とまとめている。

ここで効いているのが遅延接続だ。README は「Servers are lazy by default」と明記し、ツールを実際に呼ぶまで接続しないとしている。接続しなくても検索と説明が成立するのは、アダプターがツールのメタデータをキャッシュしているためで、README は「the adapter caches tool metadata so search and describe work without live connections」と説明する。つまり探索フェーズはディスク上のキャッシュだけで完結し、プロセス起動は実行フェーズまで遅延される。

args は JSON オブジェクトでも JSON 文字列でも受け付ける。README の推奨はオブジェクト形式で、モデルがそれを安定して扱える場合の選択肢とされている。文字列形式は単純なスキーマを必要とするプロバイダ向けに残されている。この二本立ては後方互換のための設計であり、アダプター側がスキーマの複雑さを吸収しようとしている箇所だと読める。

既存の MCP 設定ファイルをそのまま読む初回挙動

導入は pi install npm:pi-mcp-adapter の 1 行で、その後に Pi を再起動する。設定ファイルを新規に書く必要は必ずしもない。アダプターは標準的な MCP ファイルを自動で読む。

README の表によれば、.mcp.json または ~/.config/mcp/mcp.json が既にある場合、Pi はそれをそのまま使う。プロジェクトやチームでの共有には .mcp.json、全プロジェクト共通なら ~/.config/mcp/mcp.json という住み分けが示されている。初めて /mcp を開いたときには、どのファイルを検出したかの短い説明が出て、Pi がアダプター固有の上書きだけを自分のファイルに書くことが伝えられる。

ホスト固有の設定（Cursor、Claude Code、Codex など）だけがあって標準 MCP ファイルがない場合は /mcp setup を実行する。このフローは何を見つけたかを提示し、取り込む対象を選ばせ、書き込む前に実際のファイル差分をプレビューする。何も設定していない場合も同じ /mcp setup から、プロジェクトの .mcp.json かグローバルの ~/.config/mcp/mcp.json を選び、最小構成の雛形作成、既知サーバーの追加、RepoPrompt のクイック追加、マシン上で検出したものの確認へ進める。

ターミナル派向けに pi-mcp-adapter init も用意されている。インストール後に実行するとホスト固有の設定を走査し、Pi のエージェントディレクトリ（既定は ~/.pi/agent/mcp.json、$PI_CODING_AGENT_DIR が設定されていれば $PI_CODING_AGENT_DIR/mcp.json）に不足している互換インポートを追加する。

6 層の優先順位と、disable が書き込む先

設定ソースの優先順位は README に明示されている。後のものが勝つ。順に ~/.config/mcp/mcp.json、~/.agents/mcp.json、~/.agents/mcp/mcp.json、<Pi agent dir>/mcp.json、.mcp.json、.pi/mcp.json である。後ろ 2 つがプロジェクト側、真ん中の 2 つが Pi 所有の層という並びになる。

注意したいのは、Pi 所有のファイルが通常のセットアップ候補ではなく、Pi 固有設定・互換インポート・アダプター専用の上書きを保持する場所だという点だ。README は「Pi-owned files are not additional normal setup choices」とわざわざ書いている。つまり <Pi agent dir>/mcp.json と .pi/mcp.json は、日常的に編集する設定ファイルというより、アダプターが書き込む先として理解したほうがよい。

サーバーの有効・無効は /mcp disable <server> と /mcp enable <server> で切り替える。このとき永続化されるのは disabled フィールドだけで、書き込み先はプロジェクトローカルの .pi/mcp.json、すなわち最上位の Pi 層に固定されている。有効化の挙動は下位層の状態に依存する。下位層が有効ならプロジェクト側のフラグを削除し、無効な下位ソースを上書きする必要がある場合は false を書く。

重要なのは、この操作が元のソースファイルを書き換えないことだ。README は、実効サーバーが共有グローバル設定やプロジェクト共有ファイル、インポートされたホスト設定、あるいは configPath 由来であっても「the source file is never rewritten and credentials are never copied」と述べている。フラグを変えた後は /reload を実行して登録済みのツール表面を更新する必要がある。手動で同じことをするなら、任意の通常 MCP 設定のサーバーに { "disabled": true } を足せばよい。

もう 1 つ見落としやすい制約がある。createMcpAdapter({ config }) でメモリ上に渡した設定は分離されており、このプロジェクト上書きを読まないし書かない。そのモードでは /mcp disable などのコマンド自体が使えない。

ホスト設定の検出は既定で止まっている

ここは README の中で最も誤解を招きやすい箇所だ。ホスト固有の設定は /mcp setup と pi-mcp-adapter init によって検出・表示されるが、通常のセットアップ経路ではなく互換入力として扱われ、自動では読み込まれない。

具体的には、settings.hostConfigDiscovery が "off" のとき、通常の /mcp パネルはホスト固有ファイルを走査しない。既定値は "off" である。フォールバック検出を明示的に有効にするには settings.hostConfigDiscovery を "on" にするか、pi-mcp-adapter init --discover-host-configs を実行する。"prompt" という値もあり、これは検出はするが有効化はしない統合向けだと説明されている。

優先順位の面でも、ホスト設定はすべての共有ソースと Pi 所有ソースより下位に置かれる。検出時にはソースパス、由来、同名衝突が報告される。README は、外部のホストファイルに書き込むことも、そこからコマンドを暗黙に起動することもないと明記している。この設計は、他ツールの設定を勝手に実行しないという安全側の判断であり、同時に「Cursor の設定があるから Pi でも即使える」という期待は裏切られることを意味する。使いたければ /mcp setup からの明示的なインポート adoption が必要だ。

directTools と Agent Plugins という 2 つの拡張点

README は directTools という設定名を挙げ、これをアダプター専用設定の例として扱っている。インポートされたサーバーや共有グローバルのサーバーについて、Pi がこの種の設定を永続化する必要が生じたとき、書き込み先になるのが Pi 固有ファイル（<Pi agent dir>/mcp.json や .pi/mcp.json）だという文脈で登場する。プロキシ経由ではなく直接ツールとして見せたいサーバーがある場合に使う設定だと読めるが、README の抜粋には値の形式や挙動の詳細までは示されていない。ここは導入前に本体のドキュメントで確認したい部分である。

もう 1 つの拡張点が Agent Plugins だ。settings.agentPluginPaths にプラグインディレクトリを列挙すると、アダプターはそれらのパッケージから MCP サーバーを読み込める。README の例では settings.agentPluginPaths に ["./plugins/acme-tools"] を指定し、mcpServers は空のままにしている。各ディレクトリには有効な Agent Plugins 1.0 の plugin.json が必要で、これが欠けていれば読み込みは成立しない。

この 2 つは方向性が異なる。directTools はコンテキスト節約とトレードオフの関係にある（直接見せれば定義は常時展開される側に戻る）。Agent Plugins はサーバー定義の配布経路を増やすもので、コンテキスト消費そのものには影響しない。同じ設定ファイル群の中に、目的の違う拡張点が同居している構成だ。

向かない場面と、CLI ツールという対案

このアダプターが不要になる条件は README 自身が示している。MCP を使わず単純な CLI ツールを書く、という Mario Zechner の提案だ。違いは明確で、CLI ツールはツール定義をコンテキストに常駐させない。エージェントはシェルを 1 つ持てばよく、必要なコマンドはその都度組み立てる。MCP サーバーを 1 つしか使わず、しかも毎回必ず呼ぶような運用なら、プロキシを 1 段挟む分だけ呼び出しが 2 回に増える。README の例でも search と tool で 2 回だ。頻度が高く対象が固定されているなら、この 2 段階は純粋な追加コストになる。

もう 1 つの制約はメタデータキャッシュの鮮度だ。search と describe がライブ接続なしで動くのはキャッシュがあるからで、サーバー側のツール定義が変わったときに何が起きるかは README の抜粋からは確認できない。サーバーのバージョンを固定して運用する（例の chrome-devtools-mcp@1.6.0 のように）なら問題になりにくいが、追従させたい場合は検証が要る。

設定の多層構造も、チームで使うと効いてくる。6 層の優先順位と、disable が最上位の .pi/mcp.json にだけ書かれる仕様を理解していないと、「無効にしたはずのサーバーが別のメンバーの環境では有効」といった齟齬が起きる。README が「the source file is never rewritten」と繰り返しているのは、この層構造を壊さないための明示的な方針だろう。

ライセンスと保守のコスト

ライセンスは MIT で、リポジトリはアーカイブされておらず、2026-09-05 時点で最終プッシュがある。リリースは v2.32.1（2026-09-01）、v2.32.0（同日）、v2.31.0（2026-08-28）と、マイナーバージョンが短い間隔で並んでいる。README の記述量から見ても、設定ソースの解決まわりに継続的な変更が入っていることがうかがえる。

保守コストとして現実的なのは、この設定解決ロジックの変化を追う手間だ。hostConfigDiscovery の既定値、Pi 所有ファイルの位置づけ、disable の書き込み先といった仕様は README の中で繰り返し説明されており、過去に挙動が変わった可能性を示唆する。バージョンを固定して導入し、上げるときは設定の解決結果が変わっていないかを確認する運用のほうが安全だろう。

MIT ライセンスであること自体は、社内ツールへの組み込みや改変の面で制約が小さい。ただし本記事は法的助言ではなく、実際の利用条件は同梱の LICENSE ファイルと、依存する Pi 本体および各 MCP サーバーのライセンスをそれぞれ確認する必要がある。特に MCP サーバー側は npx で都度取得する構成（例の chrome-devtools-mcp@1.6.0）も取れるため、バージョン固定の有無が再現性に直結する。

編集部の結論

すでに .mcp.json や ~/.config/mcp/mcp.json を持ち、Pi で複数の MCP サーバーを併用したい人には導入の摩擦が小さい。逆に MCP を使わず CLI ツールで足りている場合や、サーバーが 1 つだけで常時接続を前提にしている場合は、プロキシを挟む意味が薄い。導入前に確認すべきは 3 点で、settings.hostConfigDiscovery が既定の "off" であること、directTools を書く先が .pi/mcp.json や ~/.pi/agent/mcp.json になること、そして settings.agentPluginPaths を使うなら各ディレクトリに Agent Plugins 1.0 の plugin.json が必要であることだ。

公式情報源

1. Issues
2. License: MIT
3. nicobailon/pi-mcp-adapter on GitHub
4. README
5. Releases