MCPのtools/list応答がttlMs/cacheScopeで拒否される問題と回避策

MCPサーバーのtools/listの結果がttlMs(鮮度期限)とcacheScope(公開範囲)の検証を通らないと、Claude CodeのMCPクライアントは応答全体を拒否します。サーバーが「接続済みなのにツールが0件」になる不具合が報告されています。報告者はクライアント側の検証が厳しすぎると見ていますが、サーバー側のパッチで解消した報告もあり、どちらに原因があるかは断定できません。利用者側の回避策は3つあります。

症状 — 接続済みなのにツールが1つも使えない

代表例として挙がっているのは、Roblox Studioが配布する公式MCPブリッジ(StudioMCP.exe)です。報告者の環境はWindows 11のClaude Codeデスクトップアプリ(Codeタブ)で、プロジェクトの.mcp.jsonにstdioサーバーとして登録しています。session_connectors_statusで見るとstatus: connectedなのに、tool_countが常に0のままです。新しいセッションを開いても、アプリを再起動しても、OSを再起動しても変わりません。

報告者はサーバー側の切り分けも自分で行っています。Claude Codeを介さず、同じ起動コマンドに素のMCP JSON-RPCを直接送ると、サーバーは28個のツールを返しました。複数のプロトコルバージョンで、応答は100ミリ秒未満でした。.mcp.jsonを書き直しても変わらないという報告も、この見立てと合います。

壊れた時期は、バージョンで追えます。次の2.1.280と2.1.281の境界は、Roblox開発者フォーラムのスレッドに書かれた報告で、issue本文の「Last working」欄は空です。

ログ(%LOCALAPPDATA%\claude-cli-nodejs\Cache\<project>\mcp-logs-<server>\*.jsonl)には、次のような検証エラーが残ります。

tools/list failed (Invalid result for tools/list: [
  { "expected": "number", "code": "invalid_type", "path": ["ttlMs"], "message": "Invalid input" },
  { "code": "invalid_value", "values": ["public","private"], "path": ["cacheScope"], "message": "Invalid input" }
]); retrying in 250ms

issueのログでは、再試行の間隔が250ミリ秒、500ミリ秒、1000ミリ秒と延び、その後にFailed to fetch toolsで打ち切られています。公式ドキュメントでは、tools/listのような能力検出リクエストは一時的なネットワークエラーやサーバーエラーなら最大3回まで短い間隔で再試行され、認証エラー・4xx応答・タイムアウトは対象外です。ここでは再試行しても同じ検証エラーが返るため、サーバーはツール0件のままになります。

原因はv2 MCPクライアントランタイムの検証

Claude CodeのMCPクライアントには2つのランタイムがあります。v1はMCP TypeScript SDK 1.x、v2は同じコードをSDK 2.0上で動かしたもので、v2だけがMCPプロトコルリビジョン2026-07-28に対応します。このリビジョンで、tools/listなど一覧系メソッドの結果に鮮度ヒントを載せるttlMsとcacheScopeが加わりました。サーバーは結果に必ず付ける(MUST)ことになっています。MCPのttlMsとcacheScopeの仕様解説にあるとおり、ttlMsは結果を新鮮とみなしてよいミリ秒数、cacheScopeはpublic(誰でも再利用可)かprivate(同一認可コンテキストのみ)かを示します。

ログから言えるのは、ネゴシエーション後(negotiatedProtocolVersionが2026-07-28)のtools/listで、ttlMsの型とcacheScopeの値が検証を通らず、応答全体が捨てられている点までです。エラーに出るのはexpected: numberとinvalid_typeだけで、受け取った値は残りません。値が数値でなかったのか、フィールドが無かったのかは、ログからは区別できません。

報告者は「サーバーが余分なフィールドを付けたために拒否された」と書いていますが、ログが示すのは余分なフィールドではなく、ttlMsとcacheScopeの値の検証失敗です。仕様では2つともサーバーが必ず付ける項目で、無い場合にクライアントが仮定する既定値は0(即失効)です。それでもClaude Code側は、欠落した応答も拒否しているように見えます。この食い違いが、冒頭で「どちらに原因があるか断定できない」と書いた理由です。

クライアント側の検証で応答が拒否される不具合は、ほかにもあります。outputSchemaにdraft-07の$schemaを宣言したツールが「unsupported dialect」で拒否される件が、MCP outputSchemaがdraft-07で拒否される問題で報告されています。任意パラメータにdefaultを宣言したツールが呼び出しごと拒否される不具合は、Claude CodeのMCPツールが応答しない原因と回避策(任意パラメータ省略時)で扱っています。

3つの回避策から選ぶ

MCP_PROTOCOL_NEGOTIATIONは、autoにするとHTTP・claude.aiコネクタ・stdioの各サーバーへ2026-07-28の問い合わせを送り、応答が無ければ旧プロトコルで接続します。未設定でも、stdioはv2.1.292以降のすべてのインストールで問い合わせます。claude.aiコネクタはv2.1.295以降、機能フラグを取得しないインストールでも既定で問い合わせます。

ここで時期のずれがあります。報告は、stdioサーバーでv2.1.281〜v2.1.283から出ています。stdioを全インストールで既定にしたのはv2.1.292で、報告の版より後です。報告の版では、stdioへの問い合わせはまだ既定ではありませんでした。症状との関係を確かめるには、legacyで症状が消えたかどうかを前後で比べるのが確実です。

# 環境変数で回避する場合(セッションごと)
MCP_PROTOCOL_NEGOTIATION=legacy claude

恒常的に固定したい場合は、settings.jsonのenvキーに書きます。

{
  "env": {
    "MCP_PROTOCOL_NEGOTIATION": "legacy"
  }
}

スレッドには、Claude Codeデスクトップアプリで同じことをする方法を尋ねるコメントもありますが、確定した答えは書かれていません。legacyで解決したというコメントは、コマンドラインからclaudeを起動した環境のものです。

バージョンを固定してダウングレードする

公式のインストール手順では、install.shにバージョン番号を渡して特定バージョンを入れる書き方が示されています。

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.280

claude installコマンドでも、[target]にバージョンを渡せます。v2.1.289でclaude --versionとclaude install --helpを実行した出力は次のとおりです。

claude --version
claude install --help

2.1.289 (Claude Code)
Usage: claude install [options] [target]
 
Install Claude Code native build. Use [target] to specify version (stable,
latest, or specific version)
 
Options:
  --force     Force installation even if already installed
  -h, --help  Display help for command

固定を保つには、バックグラウンドの自動更新を止めます。DISABLE_AUTOUPDATER=1は自動更新だけを止め、手動のclaude updateは使えます。DISABLE_UPDATES=1は、claude updateとclaude installも含めてすべての更新経路を塞ぎます。バージョンを指定して入れ直した後で設定するのが順序になります。

自分の環境がこの症状か切り分ける

/mcpの表示にも手がかりがあります。changelogには、tools/listに失敗したサーバーを「connected · tools fetch failed」と示す修正が入っています。issueの報告者が使ったsession_connectors_statusは、同じ失敗をstatus: connected・tool_count: 0としか出していません。表示が「tools fetch failed」でない場合も、ログまで見たほうが確実です。

組織全体に同じ回避策を配布する

複数の開発者が同じstdio MCPサーバー(社内ツール連携や、今回のようなゲーム開発ツールの公式ブリッジなど)に依存している場合、各人のsettings.jsonに書かせるのは崩れやすい運用です。環境変数の配布は、Managed MCPで許可リストを管理する記事で扱う管理設定ファイル(managed settings)経由で行えます。管理設定は設定の優先順位で最上位にあるため、修正版が出るまで組織全体に同じenvを一括で当てられます。

管理設定にはallowedMcpServersやdeniedMcpServersのような許可リスト機能もあり、envとは別の設定項目です。既存のMCPサーバー管理ポリシーを上書きしないよう、足すenvキーの範囲を組織内で決めてから展開します。

サーバー側の対応で直ったケース

この不具合はサーバーとクライアントの組み合わせで起きるため、サーバーの更新で解消した例があります。前述のStudio側パッチのように、サーバー提供元の対応で解消する場合があります。

issueには「最新のCLI 2.1.183でツールが返った」というコメントがあります。changelogでは2.1.183は2026年6月19日のリリースで、issueの時期とは合いません。Roblox開発者フォーラムのスレッドには、2.1.283でも同じ症状だったとの投稿があるため、打ち間違いの可能性があります。別の利用者は、サーバー更新後も「接続はするがツールを呼び出せない」状態が続き、MCP_PROTOCOL_NEGOTIATION=legacyで解決したと書いています。サーバー側の更新だけで全員の環境が直るとは限らず、legacyの併用が要った例です。

サーバー開発者がログで見る点は3つです。ttlMsとcacheScopeが応答から欠けていないか、ttlMsが数値か、cacheScopeが"public"か"private"のどちらかか、を確かめます。該当するサーバーを使う利用者には、ここまでの回避策を案内すると復旧が早まります。

まとめ

ttlMs・cacheScopeはMCPプロトコルリビジョン2026-07-28で加わった、tools/list応答の鮮度ヒントです。v2 MCPクライアントがこれをinvalid_type・invalid_valueで拒否し、サーバーのツールが0件になる不具合が、2026年9月26日以降に報告されています。changelogのv2.1.289までの項目に、この検証エラーに触れたものはありません。

ログのpathにttlMsかcacheScopeが出ていれば、最新版のまま使えるMCP_PROTOCOL_NEGOTIATION=legacyが最初の選択肢です。CLIを戻す方法はほかの修正も巻き戻します。サーバー提供元が対応済みなら、サーバー側の更新で足りる場合もあります。