MCP stdio サーバが Windows で「接続済み」のまま死んでいるのを見抜く

AI コーディングエージェント（MCP クライアント）に stdio 型の MCP サーバを登録したのに、 サーバ一覧では緑の「Connected」なのに、ツールを呼んだ瞬間だけ失敗する——という故障がある。 接続表示を信じたせいで原因の切り分けが数セッションにわたって空転しやすい。

この指示書は、その故障の3つの層と、どこまで通ったかを層ごとに証明する手順を与える。

---

前提

• MCP サーバを stdio（子プロセスを spawn して JSON-RPC を標準入出力で話す）で登録している
• 実行環境が Windows
• 登録は { "type": "stdio", "command": "...", "args": [...], "env": {...} } の形

---

1. なぜ「Connected」が嘘をつくのか

クライアントが Connected と表示する条件は MCP サーバ本体との initialize ハンドシェイクが成立したことだけ。 そのサーバが内部でさらに別の CLI を子プロセスとして起動するラッパー型（よくある形）の場合、 ラッパー自身は正常に起動するので Connected になる。中の CLI の起動失敗は、ツールを呼ぶまで表面化しない。

したがって故障は独立した3層に分かれる。

層	症状	一覧表示
① クライアント → MCP サーバの起動	CONNECT_TIMEOUT / CONNECTION_CLOSED	赤
② MCP サーバの初期化・ツール登録	ツール一覧が空	緑
③ MCP サーバ → 内部 CLI の spawn	ツール呼び出しだけ spawn <cli> ENOENT	緑

**①②が緑でも③で死ぬ。**③まで実際に叩かない限り「直った」と言ってはいけない。

---

2. Windows 固有の真因：spawn("cli") は .cmd を起動できない

Node.js のラッパーが spawn("mytool") を shell なしで呼んでいると、Windows では必ず ENOENT になる。 グローバルインストールされた npm パッケージの実体は

• %APPDATA%\npm\mytool.cmd（バッチ）
• %APPDATA%\npm\mytool（sh 用 shim。Windows からは実行できない）

の2つで、拡張子なしの mytool という実行可能ファイルは存在しない。 Windows の CreateProcess は PATHEXT 解決をしないので、spawn("mytool") は解決に失敗する。

派生: spawn("npx", ...) も同じ理由で死ぬ（npx.cmd しか無い）。 「--allow-npx を付ければ回避できる」は成立しない。

回避の選択肢

1. .cmd を解決するラッパーに乗り換える（メンテされている代替パッケージを探す。これが最短）
2. 自前の最小 MCP サーバを書く。Windows なら cmd.exe /c mytool.cmd、それ以外は素の mytool を spawn する。 JSON-RPC は改行区切り JSON なので外部依存ゼロで書ける
3. spawn(cmd, args, { shell: true }) にする（引数のエスケープが自前になる点に注意）

更新が止まったラッパーパッケージを使い続けない。 最終更新が1年以上前なら、 Windows 対応の修正はもう入らないと考えて乗り換えるほうが速い。

---

3. 副次の罠：起動コマンドの形が接続タイムアウトを作る

登録を command: "npx", args: ["-y", "<package>"] にすると、 そのマシンで初回だけ npx がパッケージをダウンロードする。 MCP クライアントの接続タイムアウトは短い（30秒程度）ので、 初回起動だけ CONNECT_TIMEOUT になり、2回目以降はキャッシュが効いて通る。

• 「昨日は繋がらなかったのに今日は繋がる」はこれ。設定を直したからではない
• 検証機がキャッシュ済みだと再現しないので「直った」と誤判定する
• 恒久対策は command: "node", args: ["<絶対パス>"]（ローカル実体を直に起動）

配布する自動修復コードが登録を無条件で npx 形式へ書き戻していないか確認する。 1台で直しても、配布側が npx 形式を強制していれば、次回起動で全台が元に戻る。

---

4. 認証設定のスキーマ移行で静かに無効化される

CLI 側の設定ファイルは、メジャー更新でキーの位置が変わることがある。 古いキーはエラーにならず単に読まれないので、「認証方式が未設定です」とだけ言われて原因が見えない。

• 旧: { "selectedAuthType": "..." }（トップレベル）
• 新: { "security": { "auth": { "selectedType": "..." } } }（ネスト）

症状が「設定したはずの値が効いていない」なら、まず CLI の現行バージョンの設定スキーマを確認する。 また、ヘッドレス実行では「信頼されたディレクトリではない」で止まる CLI があるため、 --skip-trust 相当のフラグか、それに対応する環境変数を登録の env に入れる。

---

5. 層ごとに証明する手順（これをやる）

手順 A: 層②を証明する — initialize + tools/list を直に叩く

登録とまったく同じ command / args / env で子プロセスを起こし、時間を測る。

// probe-mcp.mjs — 使い方: node probe-mcp.mjs <command> <args...>
import { spawn } from 'node:child_process';
const [, , cmd, ...args] = process.argv;
const t0 = Date.now();
const env = { ...process.env, /* 登録の env をここに再現する */ };
const p = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'], env, shell: process.platform === 'win32' });
let buf = '', err = '';
p.stderr.on('data', (d) => { err += d; });
const send = (o) => p.stdin.write(JSON.stringify(o) + '\n');
p.stdout.on('data', (d) => {
  buf += d;
  for (const line of buf.split('\n').slice(0, -1)) {
    if (!line.trim()) continue;
    let m; try { m = JSON.parse(line); } catch { continue; }
    if (m.id === 1) {
      send({ jsonrpc: '2.0', method: 'notifications/initialized' });
      send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
    }
    if (m.id === 2) {
      console.log(`OK in ${Date.now() - t0}ms tools=[${(m.result?.tools || []).map((t) => t.name).join(', ')}]`);
      p.kill(); process.exit(0);
    }
  }
  buf = buf.slice(buf.lastIndexOf('\n') + 1);
});
send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'probe', version: '0' } } });
setTimeout(() => { console.log(`TIMEOUT ${Date.now() - t0}ms`); console.log('stderr:', err.slice(0, 800)); p.kill(); process.exit(1); }, 90000);

**所要ミリ秒を必ず記録する。**クライアントの接続タイムアウトと比較するための数字であって、 「通った / 通らない」の二値では §3 の初回ダウンロード問題を見逃す。

手順 B: 層③を証明する — tools/call を1回だけ実行する

**ここを飛ばすと検証にならない。**手順 A のスクリプトの tools/list を差し替える。

send({ jsonrpc: '2.0', id: 3, method: 'tools/call',
       params: { name: '<ツール名>', arguments: { /* 最小の引数 */ } } });

判定はレスポンス本文で行う。

• spawn <cli> ENOENT → §2 の未解決。配線の問題
• 上流 API のエラー（クォータ超過・レート制限・認証失敗）→ 配線は生きている。 子プロセスの起動・認証・ネットワーク到達まで全部通った証拠なので、これは合格として扱う
• 正常応答 → 合格

**「上流のクォータ超過」を故障と読み違えないこと。**それは到達できた証明であって、設定の不具合ではない。

手順 C: 変更したら読み戻す

登録ファイルを書き換えたら、書いた直後に読み直して command / args / 必須の環境変数キーの有無を表示する。秘匿値は長さだけ出す（値を出力しない）。

---

6. 自動修復コードのレビュー観点

登録を自動で書き戻す仕組みを配っている場合、次の2つを必ず確認する。

1. 秘密を無条件に上書きしていないか。 env: { API_KEY: keyReadFromSomewhere } と書くと、読み取りに失敗した環境で 空文字が既存の有効な鍵を上書きして潰す。既存値を引き継ぐか、読めなければ書き換えを中止する
2. 「互換」の判定が形の一致になっていないか。 args に特定の文字列が含まれるかで互換性を判定すると、 より良い形（絶対パス直起動など）に手で直した端末を毎回壊しに行く

---

7. チェックリスト

• 一覧の Connected を根拠にしていない
• 手順 A で initialize + tools/list を実測し、所要ミリ秒を記録した
• 手順 B で tools/call を1回実行し、ENOENT が出ないことを確認した
• 上流のクォータ／レート上限エラーを「配線は生きている」と正しく解釈した
• 起動コマンドが初回ダウンロードを伴う形になっていない（または許容できると確認した）
• CLI 側の設定スキーマが現行バージョンのものになっている
• 自動修復コードが鍵を空文字で潰さない／手で直した登録を壊さない
• 書き換え後に読み戻して確認した（秘匿値は長さのみ表示）