PaPoo
cover

tools fetch failed が出るときに先に見ること

tools fetch failed は、MCP の tools 取得に失敗したときに claude mcp list や claude mcp get 側で見える症状です。今回の issue 群では、見え方は似ていても中身が違いました。ひとつは HTTP MCP サーバーの tools/list、もうひとつは stdio MCP サーバーの初回応答遅延です。

まず、自分のケースがどちらに近いかを切り分けます。HTTP サーバーを使っていて、claude mcp list では接続自体はできているのに ! Connected · tools fetch failed になるなら、#77106 の症状に近いです。この issue では、tools/list の返答に recursive な outputSchema の $ref cycle があると、Claude Code 側で tools の取得だけが失敗すると報告されています。報告文には「サーバーは接続と認証に成功するが、tool discovery が静かに失敗する」とあります。

一方で、stdio の MCP サーバーを使っていて、起動直後の初回リクエストに 3 秒前後かかるような場合は、#102942 の線があります。ここでは Claude Code が server/discover を投げ、タイムアウトすると同じプロセスに initialize を送り直します。その結果、古い server/discover が stdin に残り、dual-era のサーバーが tools/list を拒否して tools fetch failed に至る、という説明でした。

私の検証環境で実際に取れた出力はこれだけです。

[env_summary]
OS          : Linux 3.10.0-1160.76.1.el7.x86_64 (x86_64)
Python      : 3.8.13
検証日時    : 2026-10-18T08:56:40+09:00

この時点で言えるのは、少なくとも今回の症状クラスタは「tools fetch failed が出る」という現象の束であって、原因はひとつではない、ということです。claude mcp list で HTTP 接続は生きているのに tools だけ落ちるなら #77106 を、stdio で起動直後の遅さが絡むなら #102942 を疑うのが近道です。どちらも、ここで確認できた範囲では「tools fetch failed が出る」以上の共通点はありません。

検証環境の実測値だけでは再現条件までは確定できません。再現を詰めるなら、まずは MCP サーバーが HTTP か stdio か、そして tools/list や初回応答に時間がかかっていないかを見ていくのがよさそうです。


検証環境

OS          : Linux 3.10.0-1160.76.1.el7.x86_64 (x86_64)
Python      : 3.8.13
検証日時    : 2026-10-18T08:56:40+09:00

参照した Issue(anthropics/claude-code): #102942, #77106

同じ著者の記事