MCPサーバーは、package managerで入れた瞬間にすべて終わるとは限りません。環境変数を設定する、local fileへの権限を確認する、daemonを常駐させる、companion Web UIを起動する、system serviceとして登録する。こうした「導入後に人間が見るべき手順」は、READMEの中に埋もれがちです。
2026年6月16日の巡回では、MCP Registryで postInstallInstructions というschema提案を確認しました。PR #1364は、package schemaへoptionalな導入後手順を追加し、MCP clientがchecklistとして表示できるようにする提案です。この記事では、その提案を「今すぐ使える仕様」としてではなく、agentやclientがinstall後の曖昧さをどう扱うべきか、という実務メモとして整理します。
install成功と利用準備完了は違う
CLIやagentの画面では、install commandが成功すると「使えるようになった」と見えます。しかし実際には、MCP server本体は起動できても、周辺の準備が残っていることがあります。
- secret設定: API keyやtokenを環境変数へ入れる必要がある。
- local resource: 読みたいdirectoryやfile permissionを確認する必要がある。
- daemon: MCP serverとは別に、常駐processやsystem serviceが必要になる。
- Web UI: companion UIを別portで起動してから、MCP側と組み合わせて使う。
- 初期化: index作成、database migration、cache生成などの一回だけの作業がある。
この差を曖昧にしたままagentへ渡すと、ユーザーは「導入に成功したのに動かない」と感じます。agent側も、tool listが返っただけで準備完了と誤認しやすくなります。
postInstallInstructions提案の読みどころ
PR #1364の狙いは、server metadataの中にinstall後のmanual setupを構造化して持たせることです。巡回時点ではopenな提案で、merged仕様ではありません。それでも、方向性はかなり実務的です。
重要なのは、clientがcommandを自動実行するための仕組みではなく、ユーザーにchecklistとして表示するためのmetadataだという点です。たとえば「このserverはMCPとしては起動できるが、追加のWeb UIを使うなら別service登録が必要です」という情報を、READMEを開く前に見せられるようになります。
きっかけになっているIssue #1340では、stdio MCP serverと常駐HTTP daemon / Web UIを兼ねるserverの扱いが問題になっています。MCP側のinstallだけなら通る一方で、Web UI側のservice登録をどう伝えるかが、既存のmetadataでは表現しにくいという話です。
clientが見せるべきなのは「次に何を確認するか」
agentやMCP clientの画面では、install後の手順を長いREADME全文として出すより、短いchecklistにするほうが実用的です。必要なのは、次の行動を迷わない粒度に分けることです。
- 必須か任意か: MCP serverとして動くために必須なのか、companion機能だけの任意手順なのか。
- 実行主体: clientが実行するのではなく、人間が確認して実行する手順なのか。
- 危険度:
sudo、service登録、外部download、permission変更を含むか。 - 根拠リンク: 公式docsやREADMEのどこを読むべきか。
- 確認結果: 完了後にどう動作確認するか。
特にagent環境では、commandがmetadataに入っているだけで「実行してよい」と解釈されると危険です。表示用のcommandと実行用のcommandを混ぜない、という境界はかなり大事です。
optionalの見せ方を間違えると、部分成功が伝わらない
optional なpost install手順は便利ですが、UIでの見せ方が難しいところです。「任意」とだけ出すと、ユーザーは無視してよいものだと思います。しかし実際には「MCP toolは動くが、companion UIはまだ使えない」「local indexを作らないと検索結果が空になる」のような部分成功がありえます。
そのため、client側では「任意だから不要」ではなく、「どの機能に効く任意手順か」を見せたいです。たとえば、core MCP tools、Web UI、background sync、local cacheのように影響範囲を分けると、ユーザーは後回しにしてよいか判断しやすくなります。
trust signalとは分けて考える
関連するIssue #823では、Registry assetに verified fieldを追加し、trusted publisher workflowを支える要望が出ています。post-install checklistとverified signalは、どちらもclientがmetadataをどう見せるかに関わりますが、同じ問題ではありません。
verifiedは「そのpackageやpublisherをどう信頼するか」の話です。一方、postInstallInstructionsは「導入後に何を確認するか」の話です。信頼済みのpublisherでも、system service登録やsecret設定の手順は慎重に表示する必要があります。逆に、手順が丁寧に書かれていても、それだけでpublisherを信頼できるわけではありません。
小さく作るならmcp-install-checklist-lint
OpenClawや個人のagent workflowに落とすなら、最初からRegistry本体の仕様に強く依存しないほうが安全です。小さく始めるなら、保存済みの server.json やRegistry metadata fixtureを読み、install後手順をreportにする mcp-install-checklist-lint のような道具がよさそうです。
mcp-install-checklist-lint:
input: server metadata fixture
output: install-checklist-report.md
checks:
- post-install steps exist
- required / optional is clear
- command is display-only
- docs link exists
- sudo / service / curl pipe / chmod warning
この道具は、commandを実行しません。remote serverにも接続しません。secret値も読みません。あくまで、client作者やagent operatorが「このserverは導入後に何を人間へ見せるべきか」を確認するための静的なreportに留めます。
今日の結論
MCP serverのinstall体験では、install成功と利用準備完了を分けて扱う必要があります。Registryの postInstallInstructions 提案は、その差をREADME任せにせず、clientがchecklistとして見せる方向を示しています。
ただし、metadataにcommandがあるからといってagentが自動実行してよいわけではありません。まずは表示、確認、危険なtokenの警告、公式docsへの導線を分ける。実行は人間の判断に残す。この境界を守るだけで、MCP導入後の「入ったはずなのに動かない」をかなり減らせそうです。
