# CLI をラップした MCP サーバが上流の無料枠終了で死んだら、REST 直叩きへ寄せる **対象**: 外部 AI の CLI（`xxx-cli`）を子プロセスで起動する形の MCP サーバを運用していて、ある日から呼ぶたびに失敗するようになった状態。 **結論**: CLI を挟むのをやめて、同じ API キーで **REST を直接叩く MCP サーバに置き換える**。CLI は「自分では選べないモデル」と「自分では見えない認証経路」を勝手に決めてしまうため、上流の課金・モデル世代の変更を丸ごと被る。 --- ## 1. まず切り分ける（ここを飛ばすと直したつもりで直っていない） CLI 経由の失敗は、見た目が同じでも原因が層で分かれている。**上から順に潰す**。 | 層 | 症状の例 | 確認方法 | |---|---|---| | ① 認証方式 | `IneligibleTierError` / `UNSUPPORTED_CLIENT` / 「このクライアントはサポート対象外」 | CLI を素で1回叩く | | ② モデル世代 | `404 ... no longer available to new users` | REST に**現行モデル名**で1発投げる | | ③ 無料枠の割当 | `429 ... free_tier_requests, limit: N, model: <古いモデル名>` | 429 本文の `model:` を読む | | ④ 機能単位の割当 | 素の生成は 200 なのに、特定機能を付けた時だけ 429 | 同じキー・同じモデルで A/B する | **決定的な判別は「CLI を外して REST を直接叩く」こと。** CLI が 429 で REST が 200 なら、枯れているのは**アカウントの枠ではなく CLI が掴んでいるモデル**である。 ```bash # CLI 経路（失敗する） -p "hi" -m <現行モデル> # REST 経路（同じキーで成功するなら CLI が犯人） curl -s -X POST "https:///v1beta/models/<現行モデル>:generateContent" \ -H "x-goog-api-key: $API_KEY" -H "content-type: application/json" \ -d '{"contents":[{"parts":[{"text":"hi"}]}]}' -o - -w '\n%{http_code}\n' ``` ### 見落としやすい罠 - **CLI がモデル指定を無視することがある**。`-m <現行モデル>` を渡しても 429 本文の `model:` は旧世代のまま、ということが起きる。**429 の本文に出るモデル名を読むこと**（自分が渡した名前だと思い込まない）。 - **CLI をアップグレードしても直らない**ことがある。既定モデルがハードコードに近い形で古いままなら、バージョンを上げても同じ 429 になる。「最新版にしたのに直らない＝別の原因」ではなく「最新版でも既定は古い」が正解のことがある。 - **無料枠は機能ごとに別バケツ**。素の生成は通るのに検索グラウンディングだけ 429、という分かれ方をする。しかもこの 429 は `violations` が空で理由が出ないことがある。 --- ## 2. 置き換え方（MCP のプロトコル部分は触らない） 既存サーバの **ツール名・inputSchema・JSON-RPC の処理は一切変えない**。変えるのは「実行部」だけ。ツール名を変えるとクライアント側の登録が壊れ、復旧がもう一段増える。 ```js export async function runModel(prompt, model, options = {}) { const env = options.env ?? process.env; const key = env. ?? readKeyFromDotenv(options.homeDir); // 無ければ ok:false を返す。throw しない if (!key) return { ok: false, text: ' が見つかりません' }; const fetchImpl = options.fetchImpl ?? globalThis.fetch; // テストで差し替える口を必ず開ける const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), timeoutMs(env)); const body = { contents: [{ parts: [{ text: prompt }] }] }; if (options.grounding === true) body.tools = [{ : {} }]; try { const res = await fetchImpl(`https:///v1beta/models/${encodeURIComponent(model || DEFAULT_MODEL)}:generateContent`, { method: 'POST', headers: { 'x-goog-api-key': key, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: controller.signal, }); const raw = await res.text(); if (!res.ok) return { ok: false, text: `REST ${res.status}: ${raw.slice(0, 800)}` }; // 本文を捨てない const parsed = JSON.parse(raw); // parts には text を持たない要素（署名・思考メタ）が混ざる。text だけ拾って連結する const text = parsed.candidates?.[0]?.content?.parts ?.map((p) => p.text).filter((t) => typeof t === 'string' && t).join(''); return text ? { ok: true, text } : { ok: false, text: `REST: 応答に text がありません: ${raw.slice(0, 400)}` }; } catch (e) { if (controller.signal.aborted) return { ok: false, text: 'timeout' }; return { ok: false, text: `REST failed: ${e instanceof Error ? e.message : String(e)}` }; } finally { clearTimeout(timer); } } ``` ### この置き換えでついでに消える問題 - **起動が速くなり、MCP の接続タイムアウトが消える**。CLI 起動は依存の読み込みで数十秒かかることがあり、`CONNECT_TIMEOUT` の温床になる。 - 端末装飾（ANSI）や「色数が足りません」系の警告が**回答本文に混入しなくなる**。CLI 経由では出力を行単位で削る後処理が要る。 - OS ごとの起動差（Windows の `.cmd` は `CreateProcess` で直接起動できず `cmd.exe /c` を挟む必要がある等）が丸ごと不要になる。 - 「信頼されていないディレクトリでは動かない」系のガードを外すフラグが不要になる。 --- ## 3. 失敗は握り潰さない（特に検索系） **機能が使えないときに「使えないまま答えを返す」設計にしないこと。** 検索グラウンディングが 429 のときに、黙って検索なしで生成して返すと、呼び出し側には**検索した結果に見える**。ハルシネーションを仕様として組み込むことになる。 ```js // 429 のときだけ、なぜ落ちたかを本文に足して「失敗のまま」返す const hint = res.status === 429 && options.grounding === true ? '\n(検索グラウンディングは無料枠では使えません。素の生成は使えます)' : ''; return { ok: false, text: `REST ${res.status}: ${raw.slice(0, 800)}${hint}` }; ``` 安いモデル・無料枠は**黙って死ぬ**のが最大の危険で、上位のエージェントが気付かずに自分で処理を巻き取り、コストが静かに戻る。**枠切れは必ず声を出して落とす。** --- ## 4. 検証（緑を3つ揃えても足りない） | 見た目 | 何を証明するか | |---|---| | MCP クライアントが `connected` と表示 | **プロセスが起動して initialize に応答しただけ**。ツールが動く証拠にはならない | | 単体テストが全部緑 | スタブした fetch の契約を守っただけ。**上流の実際の応答は1度も見ていない** | | ツールを1個叩いて成功 | その1個だけの証拠。機能ごとに枠が別なので他は落ちうる | **最低ライン: サーバを実際に起動し、stdio で `initialize → tools/list → tools/call` を全ツール分流して本文を見る。** ```js // 検証ドライバの骨子（実プロセスを起動して JSON-RPC を1行ずつ流す） const server = spawn(process.execPath, ['.mjs'], { stdio: ['pipe', 'pipe', 'inherit'] }); const call = (method, params) => new Promise((resolve) => { /* id を採番して stdout の同 id を待つ */ }); await call('initialize', { protocolVersion: '' }); const list = await call('tools/list', {}); for (const tool of list.result.tools) { const r = await call('tools/call', { name: tool.name, arguments: sampleArgsFor(tool) }); console.log(tool.name, 'isError=', r.result?.isError === true, r.result?.content?.[0]?.text?.slice(0, 300)); } ``` 実際にこれで、**単体テスト 7/7 緑・接続も緑のまま、2つのツールのうち1つだけが 429** という状態が見つかる。 --- ## 5. 運用側の注意 - **並行して別のセッション／別の作業が同じ作業ツリーを触る環境では、未追跡ファイルは消える**。他所の `git clean` や巻き戻しの巻き添えで、書いたばかりの新規ファイルが commit の裏で丸ごと消えることがある。**新規ファイルは書いたらすぐ追跡下に入れる**（push は不要）。 - **MCP サーバのプロセスは接続時にコードを読み込む**。ファイルを直しても、**動いているセッションは古いコードのまま**。直後の呼び出しが失敗しても実装の失敗とは限らない。クライアントを再起動して確認する。 - 設定に残った**古いモデル名は全部洗う**。`<旧モデル名>` を持つ設定・スクリプトは 404 で落ちる。 --- ## チェックリスト - [ ] 429 の**本文に出ているモデル名**を読んだか（自分が渡した名前ではない） - [ ] CLI と REST を**同じキーで A/B** したか - [ ] ツール名・inputSchema を変えずに実行部だけ差し替えたか - [ ] `fetch` をテストで差し替えられるようにしたか（テストで実ネットワークを叩いていないか） - [ ] 枠切れを**失敗のまま**返しているか（黙って劣化した答えを返していないか） - [ ] stdio で `tools/call` を**全ツール分**流したか - [ ] 新規ファイルを追跡下に入れたか ---