Claude Code ガイド

Appearance

原文（日本語訳） ​

リモートHTTPおよびSSE MCPサーバーに対してMCP_TOOL_TIMEOUTがリクエストごとのフェッチタイムアウトを延長しない問題を修正しました。この問題により、設定値に関わらずツール呼び出しが60秒で上限に達していました。

原文（英語） ​

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.

概要 ​

MCP_TOOL_TIMEOUT環境変数はMCPツール呼び出しの実行タイムアウトを制御するための設定ですが、v2.1.142以前ではリモートHTTPおよびSSEトランスポートを使用するMCPサーバーに対してこの設定が正しく反映されていませんでした。その結果、ユーザーが長いタイムアウト値を設定していても、ツール呼び出しはハードコードされた60秒の上限に達した時点で強制的に打ち切られていました。この修正により、MCP_TOOL_TIMEOUTの設定値がHTTP/SSEサーバーへのリクエストにも正しく適用されるようになり、時間のかかるMCPツール（AI画像生成、大規模ビルドタスク、データベースマイグレーションなど）を適切に実行できるようになりました。

バグの詳細 ​

発生していた問題 ​

v2.1.142より前のバージョンでは、MCP_TOOL_TIMEOUTを60秒超の値に設定しても、リモートHTTP/SSEサーバーへのツール呼び出しは必ず60秒でタイムアウトしていました。

bash
# この設定は stdio サーバーには有効だったが、
# HTTP/SSE サーバーでは無視されていた
export MCP_TOOL_TIMEOUT=300000  # 5分
claude

設定例（~/.claude/settings.json）:

json
{
  "env": {
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

上記のように設定しても、HTTPまたはSSEトランスポートを使うMCPサーバーに対するツール呼び出しは60秒で打ち切られ、以下のようなエラーが発生していました。

Error: fetch failed
TypeError: terminated

影響を受けたトランスポート ​

トランスポート修正前修正後
stdioMCP_TOOL_TIMEOUTが有効MCP_TOOL_TIMEOUTが有効
HTTP (リモート)常に60秒で上限MCP_TOOL_TIMEOUTが有効
SSE (リモート)常に60秒で上限MCP_TOOL_TIMEOUTが有効

MCP_TIMEOUTとMCP_TOOL_TIMEOUTの違い ​

これら2つの環境変数は別々のフェーズを制御します。

  • MCP_TIMEOUT: MCPサーバーの起動・接続フェーズのタイムアウト（サーバーが起動して準備完了になるまでの待機時間）
  • MCP_TOOL_TIMEOUT: 個々のツール呼び出し実行フェーズのタイムアウト（1回のツール実行が完了するまでの待機時間）

基本的な使い方 ​

環境変数で設定する方法 ​

bash
# ツール呼び出しタイムアウトを5分に設定してClaude Codeを起動
MCP_TOOL_TIMEOUT=300000 claude

# 接続タイムアウトとツールタイムアウトを両方設定
MCP_TIMEOUT=30000 MCP_TOOL_TIMEOUT=300000 claude

settings.jsonで永続設定する方法 ​

~/.claude/settings.jsonに以下を追加することで、毎回環境変数を指定せずに設定を永続化できます。

json
{
  "env": {
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

プロジェクト固有の設定は.claude/settings.jsonに記述できます。

json
{
  "env": {
    "MCP_TOOL_TIMEOUT": "600000"
  }
}

リモートHTTP MCPサーバーへの接続 ​

bash
# リモートHTTPサーバーを追加
claude mcp add --transport http my-server https://my-mcp-server.example.com/mcp

# リモートSSEサーバーを追加（非推奨: HTTPトランスポートを優先）
claude mcp add --transport sse my-server https://my-mcp-server.example.com/sse

実践例 ​

AI画像・動画生成ツール ​

AIによる画像や動画の生成は、数分かかることがあります。これまでは60秒の壁により、生成途中でタイムアウトしていました。

json
{
  "env": {
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "600000"
  }
}
bash
# 10分のタイムアウトで起動し、画像生成MCPを使う
MCP_TOOL_TIMEOUT=600000 claude
# → "MCPサーバーを使って高解像度の画像を生成して"

CI/CDビルドおよびテスト実行 ​

大規模なビルドやテストスイートの実行は60秒を超えることがよくあります。

json
{
  "env": {
    "MCP_TOOL_TIMEOUT": "1800000"
  }
}
bash
# 30分のタイムアウトで設定し、ビルドMCPサーバーを使う
MCP_TOOL_TIMEOUT=1800000 claude
# → "MCPサーバー経由でフルビルドとテストを実行して"

データベースマイグレーション ​

大量データのマイグレーションやインデックス再構築など、時間のかかるデータベース操作に対応できます。

json
{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MCP_TOOL_TIMEOUT": "900000"
  }
}
bash
# 15分のタイムアウトでデータベースMCPを使う
MCP_TOOL_TIMEOUT=900000 claude
# → "本番データベースのマイグレーションを実行して"

GitHub Actions / CIパイプラインでの使用 ​

CIパイプラインで長時間タスクを実行する場合は、環境変数として設定します。

yaml
# .github/workflows/claude-task.yml
- name: Run Claude with extended MCP timeout
  env:
    MCP_TOOL_TIMEOUT: "600000"
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude --print "MCPサーバーを使ってビルドを実行して"

MCP_TOOL_TIMEOUTの上限目安 ​

用途に応じた推奨タイムアウト値の参考として：

ユースケース推奨値設定値（ミリ秒）
一般的なAPI呼び出し2分120000
AI画像生成10分600000
ビルド・テスト実行30分1800000
大規模データ処理60分3600000

注意点 ​

  • HTTPトランスポートを優先する: SSEトランスポートは非推奨です。リモートサーバーへの接続には--transport httpを使用してください。
  • タイムアウト値は用途に応じて設定する: 不必要に大きな値を設定するとリソースを無駄に占有する可能性があります。ツールの実際の実行時間に合わせた合理的な値を設定してください。
  • MCP_TIMEOUTとMCP_TOOL_TIMEOUTは別物: MCP_TIMEOUTはサーバー起動の待機時間、MCP_TOOL_TIMEOUTはツール実行の待機時間です。両方を適切に設定してください。
  • stdioサーバーへの影響なし: この修正はリモートHTTP/SSEサーバーに特有のバグでした。ローカルのstdioサーバーは以前からMCP_TOOL_TIMEOUTを正しく適用していました。
  • v2.1.142以前のバージョンを使用している場合: アップグレードが推奨されます。回避策として、長時間タスクはstdioトランスポートのローカルプロキシ経由で実行する方法もあります。
  • タイムアウトエラーの切り分け: タイムアウトエラーが発生した際はMCP_TIMEOUT（接続フェーズ）とMCP_TOOL_TIMEOUT（実行フェーズ）のどちらに起因するかを確認してください。--mcp-debugフラグを使うとデバッグ情報を確認できます。
bash
# デバッグモードで起動してタイムアウトの詳細を確認
claude --mcp-debug

関連情報 ​