Claude Media
MCP_TOOL_TIMEOUTを設定しても5分で切れるAgent SDKのMCPツール呼び出し
Agent SDKMCPTips

MCP_TOOL_TIMEOUTを設定しても5分で切れるAgent SDKのMCPツール呼び出し

Agent SDK TypeScriptでMCP_TOOL_TIMEOUTを伸ばしてもMCPツール呼び出しが5分で失敗する既知報告と、原因が一致する公式修正、確認しておきたい設定をまとめます。

読了目安 約10分

@anthropic-ai/claude-agent-sdk で MCP_TOOL_TIMEOUT を長く設定しても、HTTP/SSE経由のMCPツール呼び出しが5分(300秒)ちょうどで失敗する報告がありました。原因として報告者が挙げたのはNode.jsの通信基盤undiciの既定タイムアウトです。この記事では報告内容と、同じ症状を修正したとみられる公式changelogの記録、現在のバージョンで確認しておきたい設定をまとめます。

GitHub issueが報告する症状

2026年1月5日、claude-agent-sdk-typescript リポジトリのissue #118として次の報告が上がりました。E2Bサンドボックス上で @anthropic-ai/claude-agent-sdk v0.1.65〜v0.1.76を使い、settings.json の env セクションで MCP_TOOL_TIMEOUT=1200000(20分)を設定した状態で、長時間実行のMCPツールを呼び出すと次のログを残して失敗します。

[DEBUG] MCP server "deep-research": Tool 'get_results' failed after 300s: fetch failed
[ERROR] TypeError: fetch failed
    at node:internal/deps/undici/undici:14900:13

設定した20分(1,200,000ミリ秒)を待たず、ちょうど300秒(5分)で fetch failed エラーが出ています。issueのタイトルは原因を「undiciの既定headersTimeoutがMCP_TOOL_TIMEOUTより優先される」としています。このissueはopenのまま残っており、コメント0件、Anthropicからの反応も付いていません。単独の報告である点は踏まえておく必要があります。

報告者の原因診断 — undiciの既定headersTimeout

スタックトレースが指しているのは、Node.js組み込みの fetch() を実装するundiciのコード位置です。undiciのHTTPクライアントには、リクエストを送ってから応答ヘッダーが届くまでの上限を区切る headersTimeout という設定項目があり、既定値は300,000ミリ秒(5分)です。CLIが内部でMCPサーバーへ送るリクエストがこの既定値を上書きしていなければ、アプリ側で MCP_TOOL_TIMEOUT をいくら伸ばしても、通信層のタイムアウトが先に効いてしまいます。issueのタイトルが指す原因はこの既定値です。ただしissue本文にはこの推定の裏付けとなる追加コードは無く、報告者自身の解釈にとどまります。

公式changelogに残る一致する修正記録

code.claude.com/docs/en/changelog を遡ると、Claude Code v2.1.274(2026年9月17日)に次の記録があります。

Fixed Streamable HTTP MCP tool calls timing out after about 5 minutes even when a longer per-server timeout was set

「Streamable HTTP経由のMCPツール呼び出しが、サーバー個別の timeout を長く設定していても約5分でタイムアウトする」不具合の修正で、症状はissue #118とほぼ一致します。Agent SDK TypeScript側の変更履歴でも、v0.3.274が「Updated to parity with Claude Code v2.1.274」と記録しており、この修正はSDK v0.3.274(2026年9月16日公開)以降に取り込まれています。

issue #118とこの修正が同一の不具合であることをAnthropicが明言した記録は見つかりませんでした。ただし「約5分」「長く設定したタイムアウトが効かない」「Streamable HTTP(type: "http" のMCPサーバー)」という3点が揃って一致しており、当時の報告と同じ系統の不具合を修正したものと見てよさそうです。issueが報告されたv0.1.65〜v0.1.76(2026年1月)からv0.3.274(同年9月)までは半年以上あり、その間は同じ制約が残っていた可能性があります。

自分の設定がこのStreamable HTTPに該当するかは .mcp.json の type フィールドで確認できます。公式ドキュメントによれば type は http に加えて streamable-http もエイリアスとして受け付けており、MCP仕様上の正式名称は streamable-http です。どちらの表記で設定していても、今回の修正の対象は同じHTTPベースの通信方式を指します。

なお、この修正より前の2026年5月14日(Claude Code v2.1.142)には、性質の異なる別の不具合も直っています。

Fixed MCP_TOOL_TIMEOUT not raising the per-request fetch timeout for remote HTTP and SSE MCP servers, which capped tool calls at 60 seconds regardless of the configured value

こちらは「60秒で頭打ちになる」バグで、issue #118が報告する300秒とは数値が異なります。5分ちょうどで切れる症状に心当たりがある場合は、v2.1.142ではなくv2.1.274(SDKはv0.3.274)以降になっているかを確認します。

MCP_TOOL_TIMEOUTを伸ばしても切れるもう1つの理由

上記の修正を取り込んだ最新版でも、MCP_TOOL_TIMEOUT だけを設定していると5分で切れることがあります。原因はundiciとは別の、Claude Code CLI自身が持つアイドルタイムアウトです。公式ドキュメントは次のように説明しています。

A tool call to an MCP server that sends no response and no progress notification for the idle window aborts with an error instead of waiting for the wall-clock limit. [...] The idle window defaults to five minutes for HTTP, SSE, WebSocket, and claude.ai connector servers, and to 30 minutes for stdio servers.

MCPサーバーが応答も進捗通知(progress notification)も一定時間返さないと、MCP_TOOL_TIMEOUT の上限を待たずに打ち切られます。この既定は、HTTP・SSE・WebSocket・claude.aiコネクター経由のサーバーでは5分です。MCP_TOOL_TIMEOUT はツール呼び出し全体の壁時計上限、アイドルタイムアウトは「応答が止まっている時間」を見る別軸の制限で、片方を伸ばしてももう片方には効きません。この機能はClaude Code v2.1.187(2026年6月23日)で追加されたもので、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT という環境変数で調整できます。

環境変数何を制限するかネットワーク型サーバーの既定
MCP_TOOL_TIMEOUT何を制限するかツール呼び出し全体の壁時計上限ネットワーク型サーバーの既定約28時間(ただしHTTP/SSE/claude.aiコネクターは各リクエストが既定60秒。MCP_TOOL_TIMEOUT かサーバー個別の timeout を60000超に設定して引き上げる)
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT何を制限するか応答・進捗通知が止まっている時間ネットワーク型サーバーの既定5分(HTTP/SSE/WebSocket/コネクター)

v2.1.142の修正は「MCP_TOOL_TIMEOUT を伸ばしても60秒の壁が動かない」バグを直したもので、60秒という既定タイマー自体は仕様として残っています。値を引き上げない限り、修正後のバージョンでもHTTP/SSE/コネクター経由のリクエストは60秒で頭打ちになります。

MCPサーバー側が処理の途中で進捗通知を送れる実装であれば、アイドルタイマーはそのたびにリセットされます。通知を送らない実装の場合は、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT を明示的に伸ばすか 0 を指定して無効化しない限り、5分で打ち切られる挙動は残ります。

今のバージョンで確認する2点

長時間MCPツールを使っていて5分前後で失敗する場合、次の2点を順に確認します。

npm view @anthropic-ai/claude-agent-sdk version

このコマンドで表示されるバージョンが0.3.274未満なら、まずアップグレードでStreamable HTTPの不具合修正を取り込みます。0.3.274以降であれば、原因は前節のアイドルタイムアウトである可能性が高いので、MCP_TOOL_TIMEOUT と CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT の両方を env オプションで渡します。

2つの設定は判定の起点が違います。MCP_TOOL_TIMEOUT はツール呼び出しを開始してからの経過時間そのものを見るのに対し、アイドルタイムアウトは「応答も進捗通知も届かない状態」が続いた時間だけを見ます。

import { query } from "@anthropic-ai/claude-agent-sdk";
 
const result = query({
  prompt: "長時間かかるMCPツールを呼び出す",
  options: {
    env: {
      ...process.env,
      MCP_TOOL_TIMEOUT: "1200000",
      CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT: "1200000",
    },
  },
});

MCP_TOOL_TIMEOUT と MCP_TIMEOUT の違いを含めた基本的な既定値・設定例はMCP_TIMEOUTとMCP_TOOL_TIMEOUTの違いにまとめています。

よくあるつまずき

  • MCP_TOOL_TIMEOUT を伸ばしただけで解決したと思い込む: アイドルタイムアウトは別の環境変数で、無応答のMCPサーバーに対しては効きません。両方を確認します
  • SDKのバージョンを確認せずワークアラウンドだけ探す: v0.3.274以降ならStreamable HTTPの5分頭打ちバグ自体は直っている可能性があります。まずバージョンを上げてから設定を見直す順番が無駄がありません
  • createSdkMcpServer のインプロセスサーバーにも同じ対処が効くと思う: アイドルタイムアウトはIDEサーバーとSDKインプロセスサーバーには適用されないと公式ドキュメントに明記されています。インプロセスMCPサーバー特有の別のタイムアウト不具合はMCP Stream closedエラーはAgent SDKの並列呼び出しで起きるで扱っています

対処の使い分け早見表

状況確認すること対処
SDKが0.3.274未満確認することnpm view @anthropic-ai/claude-agent-sdk version対処0.3.274以降へアップグレード
0.3.274以降でも5分で切れる確認することMCPサーバーが進捗通知を送っているか対処CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT を伸ばすか0で無効化
60秒で頭打ちになる(5分ではない)確認することv2.1.142(SDK対応版)より前かどうか対処まずバージョンアップを検討
createSdkMcpServer のインプロセスサーバーで発生確認することアイドルタイムアウトは対象外対処該当バグ(Stream closed)の対処を確認

まとめ

MCP_TOOL_TIMEOUT を伸ばしてもMCPツール呼び出しが5分で切れるという報告は、GitHub issue #118として2026年1月にAgent SDK TypeScript v0.1.65〜v0.1.76に対して上がったもので、原因を報告者はundiciの既定headersTimeoutと推測しています。issue自体はAnthropicの確認を得ないまま残っていますが、公式changelogにはほぼ同じ症状を指す「Streamable HTTP MCPツール呼び出しが約5分でタイムアウトする」修正がClaude Code v2.1.274(Agent SDK v0.3.274)として記録されています。現在のバージョンで同じ症状に当たった場合は、まずSDKのバージョンを確認し、それでも切れるなら MCP_TOOL_TIMEOUT とは別軸の CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT(既定5分)を疑うのが近道です。Agent SDKでのカスタムMCPサーバーの作り方はAgent SDKカスタムツールの作り方で解説しています。

この記事を共有:XはてブLinkedIn

関連する記事

Agent SDK をもっと見る →