MCPサーバーをCLI AgentやCoding Agentに追加する時、最初に見がちなのは「設定ファイルに書けたか」「tool一覧が出るか」です。これは大事ですが、実運用で困るのはもう少し後です。接続はできたのにプロセスが残る、stderrだけが増える、unknown toolの扱いがclient側で想定と違う、という種類の不具合は、作業の最後で気づくと切り分けに時間がかかります。
2026年6月3日の調査メモでは、MCP TypeScript SDK、Go SDK、MCP Inspectorの流れを見ながら、導入前チェックを「設定の確認」から「stdio lifecycleの確認」へ少し寄せる必要があると感じました。特にCLI Agentで使うMCPサーバーは、child processとして起動されることが多く、initializeから終了までを短く観測できるだけで事故が減ります。
見るべき範囲は、起動から終了まで
小さなpreflightで見る範囲は、複雑でなくてかまいません。MCPサーバーの起動コマンドを受け取り、initialize、tool list、必要なら軽いpingやread-only tool callを実行し、最後にcloseして、processが終了したかを見る。この流れだけでも、導入直後の「つながったように見えるが後始末が怪しい」状態を見つけやすくなります。
結果は、長いログではなく、JSONやMarkdownの短いreportで十分です。たとえば、server commandの種類、capability negotiationの要約、tool数、stderrの有無、exit code、timeout、未回収processの有無を残します。credential、private URL、実ホスト名、ユーザー固有IDはreportに出さず、再現に必要な粗いsignalだけを残すのが安全です。
Inspectorは手動確認、headless checkは再現確認
MCP Inspectorは、Resources、Prompts、Tools、Notificationsを手で確認できるdebug toolとして便利です。新しいサーバーを触って理解する時には、UIで見えることに価値があります。
一方で、cron、CI、Agent sessionの前処理としては、同じ確認をheadlessに再実行できる方が向いています。Inspectorで「何があるか」を見て、headlessなlifecycle checkで「毎回きれいに起動して終了するか」を見る。役割を分けると、手動デバッグと自動運用の両方で無理が少なくなります。
unknown toolやerror handlingも観測対象にする
MCP SDK側では、unknown toolやresourceの扱い、framework adapter、auth、transportまわりの変化が続いています。こうした変更は、serverだけでなくclientの期待値にも影響します。あるclientではtool resultのerrorとして見ていたものが、別の層ではJSON-RPC errorやpromise rejectionとして扱われるかもしれません。
そのため、preflight reportには「正常系でtool listが返る」だけでなく、「unknown toolを投げた時にどう見えるか」「close後にprocessが残らないか」「stderrに警告が出続けていないか」も入れておくと実用的です。これはSDKの良し悪しを判定するためではなく、自分のAgent runtimeでどう受け止めるかを明確にするための確認です。
最小チェックリスト
- 実サーバー設定を読む前に、syntheticまたはlocal-onlyのfixtureで確認する。
- initialize、listTools、軽いread-only call、closeの順に見る。
- stderr、exit code、timeout、未回収processの有無を短く記録する。
- unknown toolやerror responseがclient側でどう見えるかを確認する。
- reportにはcredential、private URL、host名、ユーザー固有IDを入れない。
まとめると、MCPサーバー導入前の確認は「toolが見えるか」だけでは足りません。CLI Agentで使うなら、stdio processとしてきれいに起動し、期待通りに応答し、最後に閉じるところまでを小さく見る方が安全です。大きな監視基盤を作る前に、この薄いlifecycle checkを置くだけでも、MCPまわりの切り分けはかなり楽になります。
参考: modelcontextprotocol/typescript-sdk、modelcontextprotocol/go-sdk、MCP Inspector docs
