Claude CodeのMCPがtimeoutする原因と対処法
AIエージェントナビ編集部
Claude CodeでMCP（Model Context Protocol）サーバーが時間切れで止まるとき、原因になっている設定は1つではありません。性質の違う4種類のタイムアウトがあり、どれに当たっているかで直す場所が変わります。
環境変数 MCP_TIMEOUT を大きくしても直らないことがあるのは、この変数が「サーバーが起動するまでの待ち時間」だけを決めているからです。本記事では4種類の見分け方と、公式ドキュメントに書かれている「値を上げても効かない条件」を整理します。
Claude CodeのMCP：4種のタイムアウト
| 種類 | 既定値 | 設定する場所 | 効く相手 |
|---|---|---|---|
| 起動を待つ時間 | 30000ミリ秒（30秒） | MCP_TIMEOUT |
すべての接続方式 |
| ツール実行の実時間の上限 | 100000000ミリ秒（約28時間） | .mcp.json の timeout / MCP_TOOL_TIMEOUT |
すべての接続方式 |
| 1リクエストの応答待ち | 60秒（下限） | timeout と MCP_TIMEOUT の大きい方 |
HTTP・SSE・claude.aiコネクタ |
| 無応答が続いたときの打ち切り | 300000ミリ秒（5分）／stdioは1800000ミリ秒（30分） | CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT |
IDEサーバーとSDK内蔵サーバーを除く全方式 |
Claude CodeとMCPサーバーのやり取りは、1つのタイマーで測られているわけではありません。接続の段階と通信方式に応じて、次の4種類が別々に動いています。
起動待ち時間
MCPサーバーのプロセスが立ち上がり、Claude Codeとの接続が確立されるまでの猶予時間です。
- 既定値は30,000ミリ秒（30秒）に設定されており、環境変数
MCP_TIMEOUTで変更可能です。 - 重いライブラリの読み込みや初回のコンパイルが必要なサーバーでは、この30秒を超えて失敗することがあります。
ツール実行上限
サーバーが起動したあと、1回のツール呼び出しが終わるまでを測る上限です。
- 既定は100000000ミリ秒（約28時間）で、環境変数
MCP_TOOL_TIMEOUTがこの値を決めます。 - 処理が固まったまま止まらなくなるのを防ぐ最後の歯止めで、通常の使い方で届くことはまずありません。
- 1分ほどで止まる症状は、この上限ではなく次に挙げる別のタイマーが原因です。
1リクエスト応答待ち
HTTPやSSE（Server-Sent Events）でつないでいるときだけ動く、いちばん引っかかりやすい制限です。
- サーバーから最初の応答が返るまでを測り、「60秒・そのサーバーのツールタイムアウト・
MCP_TIMEOUT」のうち最も大きい値が使われます。 - stdio（標準入出力）接続とWebSocket接続にはこのタイマーがなく、ツール実行の上限まで待ち続けます。
HTTP系で1分前後で止まるときに返るのは、次の1文だけの素っ気ないエラーです。
The operation timed out.
無応答時の打ち切り
実行中でも、応答も進捗の知らせも届かない時間が続いたときに打ち切られる仕組みです。
- 既定はHTTP・SSE・WebSocket・claude.aiコネクタが5分、stdio接続が30分です。
- v2.1.187以降の挙動で、v2.1.203より前はstdio接続が対象外でした。
タイムアウト原因の特定方法
まず、どのタイムアウトで止まっているのかを切り分けます。
接続状態の確認
そもそも接続が成立しているかを、claude mcp list で確かめます。各サーバーの横に次のいずれかが出ます。
✔ Connected ! Needs authentication ✘ Failed to connect
失敗している場合は claude mcp get <name> の Issue: 行に、サーバーが返したHTTPステータスやエラー文が出ます。認証で止まっているのか、接続自体が届いていないのかをここで分けられます（v2.1.219より前は状態だけの表示でした）。
デバッグログの活用
画面に出ない通信の中身は、ログをファイルに書き出して追います。
claude --debug-file /tmp/claude-debug.log
書き出したファイルを mcp や timeout で検索すると、どのやり取りで応答が止まったかをたどれます。起動そのものに失敗しているときは、コマンドの場所が見つかっていない場合も多く、その症状は次の記事で扱っています。
関連記事：spawn npx ENOENTでMCPが起動しない原因と対処法
サーバー単体での切り分け
Claude Codeを介さず、サーバー単体が動くかを確かめます。stdio接続なら、設定に書いた起動コマンドをターミナルで直接実行してください。
stdio接続のサーバーは標準入力と標準出力でやり取りするため、何も表示されずに止まって見えるのが正常です。逆にすぐ終了するなら、Claude Codeの設定ではなくサーバー側に原因があります。
タイムアウトの設定変更方法
当たっている場所が分かったら、対応する値を緩めます。
起動時間の延長
起動が間に合っていないときは、環境変数の一覧にある次の値を調整します。
MCP_TIMEOUTにミリ秒で指定します（例：MCP_TIMEOUT=60000 claudeで60秒）。- 起動時の接続は既定では背景で進むため、
MCP_CONNECTION_NONBLOCKINGに0を入れると最初の問い合わせ前に接続を待たせられます。 - そのとき全体を待つ時間は
MCP_CONNECT_TIMEOUT_MS（既定5000ミリ秒）で、1台ごとの接続を区切るMCP_TIMEOUTとは別の値です。
実行時間の延長
重いツールだけ延ばしたいときは、設定ファイル側に書きます。
.mcp.jsonの該当サーバーの項目に"timeout": 600000（10分）のようにミリ秒で書きます。- この値は
MCP_TOOL_TIMEOUTより優先され、そのサーバーだけに効きます。 - 測るのは1回のツール呼び出しにかかった実時間で、進捗の知らせが届いても延びません。
HTTP系の60秒制限
HTTP・SSE・claude.aiコネクタで1分前後の時間切れが続く場合は、この応答待ちのタイマーを動かします。
timeoutかMCP_TIMEOUTのどちらかを60000（60秒）より大きくすると、その分だけ待ってくれます。- 60秒より小さい値を入れても待ち時間は短くならず、下限の60秒が使われます。
- このタイマーはstdio接続とWebSocket接続にはありません。
無応答打ち切りの変更
処理は続いているのに通信だけが途切れる場合の対処です。
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUTにミリ秒で指定し、0を入れると打ち切り自体を止められます。- この打ち切りは応答も進捗の知らせも届かない時間で測るため、サーバー側から定期的に進捗を返す作りにすれば避けられます。
- サーバー単位の
timeoutを1000以上にしておくと、その値より早く打ち切られることはありません（v2.1.203以降）。
設定が効かない条件
値を大きくしても効かない、あるいは無視される場面があります。
1000未満の値の無視
.mcp.json の timeout に1000（1秒）未満を書くと、その指定は読み飛ばされ、MCP_TOOL_TIMEOUT（未設定なら約28時間）が代わりに使われます。短い上限を入れてツールを早めに切り上げさせる、という使い方はできません。
28時間制限の適用外
既定値が約28時間と長いため安心しがちですが、この値はHTTP系の応答待ちには効きません。
応答待ちのタイマーは「60秒・そのサーバーのツールタイムアウト・MCP_TIMEOUT」の最大値で決まりますが、MCP_TOOL_TIMEOUT を設定していないときの約28時間という既定値は、この比較に加えられない決まりになっています。つまり何も設定していないHTTPサーバーは、28時間ではなく60秒で区切られます。
2分超のバックグラウンド動作
止まったように見えて、実は動いている場合もあります。
会話の中で呼び出したMCPツールは、2分（CLAUDE_CODE_MCP_AUTO_BACKGROUND_MSの既定値120000ミリ秒）を超えると背景の作業へ移り、Claude Codeは待たずに先へ進みます。移った作業は /tasks で確認と停止ができます（v2.1.212以降）。時間切れと決める前に、ここを見てください。
設定で直らないタイムアウト
ここからは、値の調整では動かせないタイムアウトです。
サブプロセスの通信阻害
MCPサーバーが内部で別のコマンドを呼んでいるときに起きる詰まりです。
Google Analytics用のanalytics-mcpをClaude Codeにつないだ利用者は、ツールを動かしてもエラーすら出ずに値が返らない状態に遭遇し、その調査の経過を公開しています。原因は、サーバーの中で呼ばれる gcloud コマンドが親プロセスの標準入力、つまりClaude Codeとの通信路を受け継いで読み取りで止まることでした。サーバー自体は動いているのに応答だけが返らず、呼び出しはタイムアウトで終わります。
この利用者は、認証情報をgcloudの既定の場所とは別のパスに複製し、MCP設定の env でそちらを参照させて解決しています。サーバーが外部コマンドを呼ぶ作りになっている場合、待ち時間をいくら緩めても直らないため、呼び出し側の作りを見直すほうが早く終わります。
起動直後の切断
時間の設定ではなく、起動の途中で接続が切られているという報告もあります。
2026年8月14日に立てられたIssueでは、v2.1.228前後から、最初のやり取り（initialize）に3秒以上かかるstdioサーバーで、1回目の起動が約3秒で終了信号を受けて2回目が走る挙動が報告されています。WSL2からWindows側の実行ファイルを呼ぶ構成ではWindows側が残るため、同時に1つしか起動できないサーバーでは次の表示が出続けるとされています。
Failed to reconnect to <server>: CONNECTION_CLOSED
この報告は2026年9月20日時点で未解決のままです。同じ症状に見えるときは、待ち時間の値を変える前に、残っているサーバーのプロセスを終了させてから起動し直すと切り分けられます。
数値変更後の停止
設定できる値をすべて緩めても止まる、という報告もあります。
2026年9月9日の報告では、サーバー単位の timeout を24時間に、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT を 0 にしても、HTTP接続のツール呼び出しが約6分で終わったとされています。このIssueは2026年9月15日にクローズされています。コメントでは、原因はClaude Code側のMCPタイマーではなく、Claude Codeが同梱するBunランタイムの fetch が持つ既定300秒のアイドルタイムアウトだとする利用者の解析が投稿されました。応答のバイトが届かない間だけ時間が進むため、サーバー単位の timeout を伸ばしても効きません。ただしAnthropicからの公式の説明は、2026年9月20日時点で出ていません。
数分を超える処理をHTTP接続のMCPサーバーに任せている場合は、1回の呼び出しを短く分けるほうが確実です。
まとめ
Claude CodeのMCPが時間切れで止まったときは、まず claude mcp list で接続が成立しているかを見て、起動の段階で失敗しているのか、ツールの実行中に切られているのかを分けます。起動で止まっているなら MCP_TIMEOUT、実行中に切られているなら .mcp.json の timeout が効く場所です。
HTTP接続で1分前後や5分前後で止まる場合は、応答待ちの60秒と無応答の打ち切りが別々に動いているため、timeout を60000より大きくする、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT を調整する、の順に当たります。それでも同じ時間で止まるなら、claude --debug-file でログを残し、サーバー側の作りを疑ってください。
