10/21 の公式ドキュメント更新：MCPゲートウェイのツール検索デフォルト変更と環境変数の拡充

Posted at 2026-10-28

2026-10-21 のドキュメント更新は、Claude Code の本番運用における挙動制御の整備に集中している。MCPゲートウェイ経由のツール検索がデフォルトで有効になった経緯、環境変数による細粒度なリクエスト制御の追加、フックに加わった「defer」アクションなど、インフラ担当者と自動化パイプラインの構築者に影響が及ぶ変更が複数確認された。

MCPゲートウェイ経由のツール検索、v2.1.304 以前との挙動が逆転

MCP ページに追記された内容のうち、既存の運用に最も影響するのがゲートウェイ経由のツール検索の扱いだ。

Before v2.1.304, tool search was off behind a gateway unless ENABLE_TOOL_SEARCH was true , auto , or auto:N .

（出典 [7]）

（訳：v2.1.304 より前は、ENABLE_TOOL_SEARCH が true・auto・auto:N のいずれかでなければ、ゲートウェイ経由のツール検索はオフだった。）

v2.1.305 以降ではこの前提が逆転し、ANTHROPIC_BASE_URL でゲートウェイを指定した場合もツール検索がデフォルトで有効になる。リクエストには defer_loading フィールドと tool_reference ブロックが含まれ、ゲートウェイがこれを転送する構造だ。ゲートウェイが 400 または 422 を返した場合、Claude Code はツール検索なしで自動リトライし、成功すれば画面には何も表示されない。ただし以降のリクエストで再度ツール検索が試みられるため、繰り返し拒否される環境では ENABLE_TOOL_SEARCH=false を設定することでその往復を省ける。また特定のサーバーのツールを常にアップフロントでロードしたい場合は、そのサーバーの設定で alwaysLoad を true にすることで検索ステップを省略できる。

managed-agents-secure コマンドの追加と /doctor の使用量チェック強化

スラッシュコマンドに managed-agents-secure が加わった。

managed-agents-secure [] Read the settings of one Managed Agent and report where they match the Secure your Managed Agents deployment guide or differ from it.

（出典 [1]）

（訳：managed-agents-secure [エージェントID] は、指定したマネージドエージェントの設定を読み込み、セキュリティデプロイガイドに準拠している箇所と乖離している箇所を報告する。）

このコマンドは ant CLI v2.1.304 以降が必要だ。マネージドエージェントの展開をセキュリティガイドへの準拠状況で確認したい場合の定期チェックに使える。

/doctor にも変更がある。Pro・Max・Team・Enterprise プランのユーザーに対し、過去 7 日間の利用状況をもとにプラン使用量を削減する変更を提案する機能が加わった。Claude Code v2.1.305 以降が必要で、Remote Control 接続中は実行されない。

スキルのバックグラウンド実行に関するバグの記載も追加された。v2.1.295 より前では、スキルがバックグラウンドで実行されるとき、サブエージェントがスキルの完了を待たずに処理を続け、スキルの結果がサブエージェントではなくメインの会話に届いてしまう問題があった。この挙動は v2.1.295 で修正されている。

環境変数：タイムアウト上限の撤廃とプロンプトキャッシュ TTL の分離制御

API_TIMEOUT_MS を 0 に設定することで、API リクエストのタイムアウト上限を撤廃できるようになった。v2.1.305 以降で有効で、遅いネットワークやプロキシ経由のルーティング時に役立つ。なおローカルセッションではノンストリーミングの試行は 0 設定でも 300 秒でタイムアウトする点が明示されている。

プロンプトキャッシュの TTL をメイン会話とサブエージェントリクエストで個別に制御したい場合、2 つの変数が使えるようになった。

To choose the TTL separately for the main conversation and for requests outside it, use CLAUDE_CODE_PROMPT_CACHE_TTL and CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL , which take precedence over this variable

（出典 [6]）

（訳：メイン会話とそれ以外のリクエストで TTL を個別に指定するには、CLAUDE_CODE_PROMPT_CACHE_TTL と CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL を使う。これらは既存の変数より優先される。）

これに関連して ENABLE_PROMPT_CACHING_1H_BEDROCK は非推奨と明記された。

CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS は新しい環境変数で、使用量制限のリセット待ちをしているリクエストが制限解除を確認する最小インターバルをミリ秒で指定する。設定できる値は 60000（1 分）から 10800000（3 時間）の範囲で、範囲外または未設定の場合はチェックが行われない。claude.ai サブスクリプションのセッションまたは週次制限の場合のみ機能し、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC が設定されている間は動作しない。v2.1.305 以降が必要だ。

CLAUDE_CODE_SAFE_MODE を 1 にすることで、CLAUDE.md・スキル・プラグイン・フック・MCP サーバー・カスタムコマンド・ワークフローなどをロードしないセーフモードで起動できる。設定が壊れた場合のトラブルシューティング向けに整備された変数だ。

フックの defer アクション：ツールコールを後で再開する

フックに「defer」という新しいアクションが追加された。

defer を返すと、ターンは stop_reason が tool_deferred の結果で終了し、保留中のツールコールがトランスクリプトに残る。再開時にツールが使えない場合は stop_reason: tool_deferred_unavailable かつ is_error: true が返る。再開前にプロンプトを送った場合、Claude Code はツールの結果なしで応答し、保留されたコールは破棄される。フックは待機中に再び defer を返すことができ、allow または deny を返すまでループが続く。

バックグラウンドセッションと bypassPermissions の要件、設定場所に注意

バックグラウンドセッションで bypassPermissions を使う場合の要件が明確になった。

A background session honors your acceptance when it's recorded in user or managed settings

（出典 [11]）

（訳：バックグラウンドセッションは、ユーザーまたはマネージド設定に記録された承認を尊重する。）

.claude/settings.local.json のみに skipDangerousModePermissionPrompt を設定してもバックグラウンドセッションでは無視される。~/.claude/settings.json に設定した上で、新しいバックグラウンドセッションを起動する必要がある。

クラウドセッションの設定についても整理が加わった。プロジェクト内のクラウドスレッドでは、リポジトリの .claude/settings.json の権限ルール・フック・env は一切適用されない。複数リポジトリを持つセッションでは、各リポジトリの .claude/settings.json から enabledPlugins と extraKnownMarketplaces のみが読み込まれる。

スケジュールタスクの MCP サーバーについても記載が追加された。プロジェクト内のスケジュールタスクは .mcp.json を読み込まないため、サーバーはコネクターとして追加する必要がある。プロジェクト外のタスクではリポジトリにコミットした .mcp.json も利用できる。

その他の更新

worktrees: git 2.56 以降を使用していた v2.1.302 より前の環境で、保護されたチェックアウトのパス上に不正な .git ファイルがあると「could not be resolved」エラーが誤って表示される問題があった。v2.1.302 以降に更新することで解消する。
checkpointing: 巻き戻し後にセッションを終了すると、巻き戻したメッセージが戻ってくる場合がある。再度 /rewind で同じプロンプトを選択し「Restore conversation」を実行することで除去できる。
monitoring-usage: OpenTelemetry SDK の属性数上限が低い場合にドロップされる属性の順序が明文化された。permission_mode が最初、次に classifier_category、次に classifier_verdict の順でドロップされる。この順序保証は v2.1.302 以降の動作だ。
sandboxing: 拒否パスがシンボリックリンクを経由している場合、実体のパスも拒否される。~/.claude がドットファイルリポジトリへのリンクになっている構成では、その実体パスも制限対象になる点が明記された。
agent-sdk/structured-outputs: outputFormat（TypeScript）または output_format（Python）を設定すると、メッセージストリームに StructuredOutput という名前のツールコールが現れる。これは Claude Code が内部的に追加するツールで、アプリ側のログや UI でこのコールが表示される場合は除外する処理が推奨されている。

この日の更新が運用に与える影響

この日の更新は、ゲートウェイや API 経由で Claude Code を利用している開発者に最も直接的に影響する。ツール検索のデフォルト変更は v2.1.304 以前との後方互換性を持たず、ゲートウェイが defer_loading に対応していない環境では ENABLE_TOOL_SEARCH=false の明示設定が必要になる。環境変数については API_TIMEOUT_MS=0 と CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS の 2 つが、制限や遅延の多い運用環境でのリトライ戦略に使える新しい選択肢を提供する。バックグラウンドセッションの権限要件の明確化は、CI パイプラインや自動化スクリプトで bypassPermissions を利用しているチームが設定場所を見直す契機になる。

出典

本稿の引用はすべて一次資料と逐語照合（verify_article 通過）のうえ掲載しています（2026-10-29 検証）。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up