Claude Agent SDKにおけるMCPサーバー接続フローとalwaysLoadパラメータについて

概要

Claude Agent SDKでMCPサーバーが「pending」状態になる挙動の理由と、セッション開始時からツールを即座に利用可能にする「alwaysLoad」パラメータの詳細を解説しています。

詳細内容

Claude Agent SDK（TypeScript版）を用いてMCPサーバーに接続する際、初期化（init）メッセージでステータスが「pending」と表示され、ツール一覧が空になる挙動の仕組みと解決策を解説した記事です。これはSDKがデフォルトで非ブロッキングな遅延ロード（tool-search deferral）を採用しているためであり、必要に応じてバックグラウンドで接続が行われます。特定のツールを常に最初から利用可能にしたい場合は、設定ファイル（.mcp.json）で「alwaysLoad: true」を指定することで、起動時に接続をブロッキングし、コンテキストにツール定義を常駐させることができます。Claude Codeのアップデートに関連するパラメータであり、コンテキスト消費と利便性のトレードオフについても触れられています。

元記事を読む他のサマリーを見る