MCPツール説明文の文字数上限(既定2048文字)を変える方法
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHでMCPツール説明文とサーバー指示の2,048文字の切り詰め上限を変更する手順とMCPサーバー開発者への影響。
MCPツール説明文の文字数上限とは
Claude Codeは、MCPサーバーが提供する各ツールの説明文と、各サーバーの指示(instructions)を既定で2,048文字までに切り詰めてモデルへ送ります。超えた分はそのまま切り捨てられ、モデルには表示されません。
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH環境変数を設定すると、この上限をセッション内の全MCPサーバーに対して一括で変更できます。v2.1.280(2026年9月22日リリース)で追加された変数です。
この環境変数でできること
- ツール説明文が長いMCPサーバーを使っていて、重要な情報が2,048文字を超えて切り詰められている場合に上限を引き上げる
- 逆に、多数のMCPサーバーを同時接続してコンテキスト消費を抑えたい場合に上限を下げる
- サーバー指示(instructions)にも同じ上限が適用されるため、Tool Search有効時にClaudeがどのサーバーを検索すべきか判断する材料も、この上限の影響を受ける
使い方
シェルで一時的に設定する場合です。
export CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=4096
claude値は正の整数のみ受け付けます。文字列や負の数、0のような無効な値を指定すると、その指定は無視されて既定の2,048文字が適用されます。単位や桁区切りのカンマは付けず、半角の数字だけを渡してください。
毎回のセッションで恒久的に反映したい場合は、~/.claude/settings.jsonのenvキーに追加します。
次のように書きます。
{
"env": {
"CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH": "4096"
}
}シェルのexportはそのターミナルセッション限りですが、settings.jsonのenvキーはそのセッションの環境に書き込まれ、起動のたびに適用されます。どのファイルに書くかで、値が適用される範囲が変わります。
| 設定ファイル | 適用範囲 |
|---|---|
~/.claude/settings.json | 適用範囲自分の環境、全プロジェクト共通 |
.claude/settings.json | 適用範囲プロジェクトに関わる全員(バージョン管理対象) |
.claude/settings.local.json | 適用範囲自分の環境、このプロジェクトのみ(gitignore対象) |
| Managed settings | 適用範囲組織の全員(管理者が配布) |
チーム全体で説明文が長いMCPサーバーを使っているなら.claude/settings.jsonに、組織全体で統一するなら管理者がManaged settingsから配布するのが適しています。同じ変数がシェルと設定ファイルの両方にある場合は、envブロックの値がシェルの値を上書きします。例外はClaude Desktopアプリやセルフホスト環境のランナーから起動したセッションで、起動側がすでに同じ変数を設定している場合に限り、設定ファイルの値は無視されます。
既定値2,048文字と切り詰めの仕組み
対象になるのは次の2つです。
- 各MCPツールの説明文(ツールごとに個別)
- 各MCPサーバーの指示(instructions。サーバー単位)
どちらも2,048文字を超える部分は、モデルに送られる前に切り詰められます。ツール自体は普通に使えるので、説明文の後半に書いた注意事項や引数の詳しい仕様がモデルに届いていない状態に気づきにくい点が、この上限の厄介なところです。skillの説明文にも同種の上限があり、skillListingMaxDescCharsで変えられます。
Tool Searchとの関係
Tool Search(ツール検索)は、MCPのツール定義を必要になるまで遅延読み込みしてコンテキスト消費を抑える機能です。セッション開始時に読み込まれるのはツール名とサーバー指示だけで、説明文はClaudeがそのツールを検索したときに初めて載ります。サーバーを何個つないでもコンテキストへの影響は小さく、サーバーごとのツール数にも固定の上限はありません。
サーバー指示は、ツール名と並んで「どのサーバーのツールを検索するか」をClaudeが決める手がかりです。この指示が2,048文字で切られると、後半に書いた「いつ検索すべきか」の条件がClaudeに届きません。変数の対象にサーバー指示が含まれているのは、このためです。
ツール定義がセッション開始時に全部載る経路は3つあり、上限を上げたときの効き方が変わります。
ツール定義が先に載る3つの経路
サーバー単位で指定する
alwaysLoad: trueをサーバーの設定に書くと、そのサーバーの全ツールが毎回セッション開始時に載ります。ツール単位なら_metaの"anthropic/alwaysLoad": trueです。alwaysLoad: trueを付けると、起動時にそのサーバーの接続完了を待つようになります。待つのは通常の接続タイムアウトと同じ最大5秒までです。Tool Searchが使えない構成
ENABLE_TOOL_SEARCH=falseが代表です。ANTHROPIC_BASE_URLがAnthropic以外のホストを指すときも該当しますが、ENABLE_TOOL_SEARCHで上書きできます。Microsoft FoundryのAzureデプロイはサーバー側が拒否するので、上書きできません。auto指定で枠に収まる
ENABLE_TOOL_SEARCH=autoは、ツール定義がコンテキストの10%に収まるとき先に載せます。auto:5のように割合も指定できます。
先に載る経路では、説明文の長さがそのままコンテキスト消費になります。CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHを引き上げた分だけ、毎ターンの負担が増える構成です。遅延読み込みなら、増えるのは検索されたツールの分だけです。
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定している環境では、Tool Searchは止まったままです。ENABLE_TOOL_SEARCHを指定しても戻りません。組織がManaged settingsでTool Searchを有効のまま保つ手段は、v2.1.227以降にあります。
MCPサーバーの説明文は2,048文字に収まる前提で書く
自分でMCPサーバーを実装している場合、この上限は「ユーザー側の設定」であると同時に「サーバー側の設計指針」でもあります。公式ドキュメントは、Tool Search(ツール検索)が有効な環境ではサーバーのinstructionsフィールドがより重要になると説明しています。Claudeがいつそのサーバーのツールを検索すべきかを判断する材料になるためです。
instructionsを書くときに含めるべき要素として、公式が挙げているのは次の3点です。
- そのサーバーのツールがどのカテゴリーのタスクを扱うか
- Claudeがいつそのツールを検索すべきか
- サーバーが提供する主要な機能
ユーザー環境の上限を前提にできない以上、サーバー開発者は既定の2,048文字に収まるよう説明文を書き、重要な情報ほど冒頭に置くのが安全策になります。ユーザー側が上限を引き上げていない限り、2,048文字を超えた部分はどのユーザーの環境でも一律に切り詰められるからです。プラグインに同梱したMCPサーバーを配布する場合も同じ制約を受けます。
説明文を書くときは、要点を先頭に置き、後半にいくほど省略されても実害の小さい補足情報を置く順番を優先します。「このツールは何をするか」「いつ呼ぶべきか」「主要な引数の意味」を最初の数百文字に詰め込み、エラーハンドリングの細かい注意点や稀なエッジケースの説明は後半に回します。2,048文字ちょうどで機械的に切られるため、文の途中で説明が終わっても不自然に見えない書き方を意識しておくと、切り詰めの影響を受けにくくなります。
上限の変遷は次のとおりです。
2,048文字の上限が変わってきた経緯
- v2.1.84(2026年3月26日)2KBの上限が導入された
OpenAPIから自動生成したサーバーがコンテキストを膨らませるのを防ぐため、ツール説明文とサーバー指示が2KBで切られるようになりました。
- v2.1.162(2026年6月3日)切り詰め位置の絵文字で400エラーが出る不具合が直った
切り詰めの境目に絵文字があると、APIが400エラーを返す不具合の修正です。
- v2.1.280(2026年9月22日)環境変数で上限を変えられるように
固定だった上限を、ユーザーが全MCPサーバー一律で変えられるようになりました。
v2.1.280より前のユーザーは上限を動かせないので、説明文を削るのはサーバー開発者の側でした。v2.1.280以降は、削らずに済ませる選択肢がユーザー側にもあります。ただし変数を知らないユーザーの環境では今も2,048文字で切られるため、開発者側の書き方は変わらず効きます。
MAX_MCP_OUTPUT_TOKENSとの違い
似た名前の環境変数にMAX_MCP_OUTPUT_TOKENSがありますが、制御対象がまったく別です。
説明文の上限と実行結果の上限
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH
ツール説明文とサーバー指示を、モデルに送る前に2,048文字で切ります。切られるのは「ツールをどう説明するか」の部分です。
MCPサーバーの調子が悪いときは両方が候補ですが、症状は別です。説明文が途中で切れているなら前者、ツール呼び出し後に警告が出るなら後者を調整します。
いつ反映されるか
シェルのexportで設定した値は、Claude Codeが起動時に読み込むため、すでに起動しているセッションには反映されません。新しい値を使うには、そのセッションを終了してからclaudeを再起動します。
settings.jsonのenvキーに書いた値は扱いが異なります。ファイルを保存すると、新しい値・変更した値が実行中のセッションにも反映されます。OpenTelemetryのように変数を起動時に一度しか読まない機能だけは、再起動まで古い値のままです。この変数は、保存すると値がセッションの環境に入ります。ただし、接続済みサーバーの説明文に新しい上限が使われるかどうかは、環境変数のページに書かれていません。確実に効かせるなら、セッションを再起動します。
ファイルから変数を消した場合は逆で、実行中のセッションでは消えず、次の起動で初めて外れます。上限を既定に戻したいときは、行を消したあとにセッションを立ち上げ直します。プロジェクトやローカルの設定ファイルに書いた場合、ワークスペースを信頼する前は値が適用されないことがあります。
よくあるつまずき
- 数値以外を指定して無視される:
"4096文字"のような単位付き文字列や小数は無効値として扱われ、既定の2,048文字に戻ります。プレーンな数字だけを渡します - v2.1.280未満では効かない: この変数はv2.1.280以降が対象です。
claude --versionで確認し、古い場合はアップデートしてから設定します。バージョンアップ後もMCPサーバーに接続できない場合の切り分け手順は別記事にまとめています - シェルとsettings.jsonの二重設定: 両方に値を書くと、settings.jsonの
envブロックの値がシェルの値を上書きします。意図と違う値が効いていると感じたら、まずsettings.jsonを見ます。Desktopアプリ経由で起動したときは、起動側の設定も見ます。優先順位は設定場所の表の直後の段落のとおりです - 上限を上げてもコンテキストは無限に増やせない: Tool Searchが働く環境では、ツール定義は必要になるまで遅延読み込みされます。ただし読み込まれた説明文・指示が長ければ、その分だけコンテキストを消費します。
alwaysLoadを付けたサーバーは毎回その分を払います - サーバーごとに個別の上限は設定できない:
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHはセッション内の全MCPサーバーに一律で効きます。特定のサーバーだけ上限を変える設定項目は、環境変数のリファレンスにもMCPのページにも載っていません。MAX_MCP_OUTPUT_TOKENSにはツール単位で上限を上書きするanthropic/maxResultSizeCharsアノテーションがありますが、同様のアノテーションは説明文の側についてMCPのページに載っていません
まとめ
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHは、MCPツール説明文とサーバー指示の既定2,048文字の切り詰め上限を変える環境変数で、v2.1.280以降で利用できます。長い説明文のサーバーで情報が欠けているなら値を上げ、自分でサーバーを作るなら既定値に収める。この2択がほとんどのケースを分けます。
上限を上げる前に、使っているMCPサーバーがTool Searchの遅延読み込みに乗っているかを見ておくと順序が決まります。先に載る経路のサーバーなら、上げた分だけ毎ターンのコンテキストを消費するからです。