MCPツール説明文の文字数上限(既定2048文字)を変える方法

MCPツール説明文の文字数上限とは

Claude Codeは、MCPサーバーが提供する各ツールの説明文と、各サーバーの指示(instructions)を既定で2,048文字までに切り詰めてモデルへ送ります。超えた分はそのまま切り捨てられ、モデルには表示されません。

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH環境変数を設定すると、この上限をセッション内の全MCPサーバーに対して一括で変更できます。v2.1.280で追加された変数です。

この環境変数でできること

• ツール説明文が長いMCPサーバーを使っていて、重要な情報が2,048文字を超えて切り詰められている場合に上限を引き上げる
• 逆に、多数のMCPサーバーを同時接続してコンテキスト消費を抑えたい場合に上限を下げる
• サーバー指示(instructions)にも同じ上限が適用されるため、Tool Search有効時にClaudeがどのサーバーを検索すべきか判断する材料も、この上限の影響を受ける

使い方

シェルで一時的に設定する場合です。

export CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=4096
claude

値は正の整数のみ受け付けます。文字列や負の数、0のような無効な値を指定すると、その指定は無視されて既定の2,048文字が適用されます。単位や桁区切りのカンマは付けず、半角の数字だけを渡してください。

毎回のセッションで恒久的に反映したい場合は、~/.claude/settings.jsonのenvキーに追加します。

cat ~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH": "4096"
  }
}

シェルのexportはそのターミナルセッション限りですが、settings.jsonのenvキーはclaudeの起動方法によらず毎回適用されます。どのファイルに書くかで、値が適用される範囲が変わります。

チーム全体で説明文が長いMCPサーバーを使っているなら.claude/settings.jsonに、組織全体で統一するなら管理者がManaged settingsから配布するのが適しています。同じ変数がシェルと設定ファイルの両方にある場合は、設定ファイル側のenvブロックの値が優先されます。

既定値2,048文字と切り詰めの仕組み

対象になるのは次の2つです。

• 各MCPツールの説明文(ツールごとに個別)
• 各MCPサーバーの指示(instructions。サーバー単位)

どちらも2,048文字を超える部分は、モデルに送られる前に切り詰められます。切り詰めを知らせる警告やエラーは公式ドキュメントに記載がなく、ツール自体は使えるため、説明文の後半に書いた注意事項や引数の詳しい仕様がモデルに届いていない、という状態に気づきにくくなります。

Tool Searchとの関係

Tool Search(ツール検索)は、MCPのツール定義を必要になるまで遅延読み込みすることでコンテキスト消費を抑える機能です。セッション開始時に読み込まれるのはツール名とサーバー指示だけで、ツールの詳細な説明文はClaudeが実際にそのツールを検索したタイミングで読み込まれます。この仕組みのおかげで、MCPサーバーを何個接続してもコンテキストウィンドウへの影響は最小限に抑えられ、サーバーごとのツール数にも固定の上限はありません。

セッション開始時から常に読み込まれるサーバー指示(instructions)は、ツール名と並ぶ、Claudeがどのサーバーのツールを検索すべきかを判断する主要な手がかりになります。ここがCLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHの対象に含まれている理由です。サーバー指示が2,048文字で切り詰められると、Claudeがそのサーバーを検索候補から外してしまう可能性があります。

Tool SearchはENABLE_TOOL_SEARCH環境変数で制御でき、既定は有効(未設定)です。無効化される理由は経路によって異なります。ANTHROPIC_BASE_URLがAnthropic以外のホストを指している場合は、間にあるプロキシがtool_referenceブロックを転送できないために自動的に無効化されますが、ENABLE_TOOL_SEARCHを明示的に指定すれば上書きできます。一方Microsoft Foundry(Azureホスティング)のデプロイでは、サーバー側の実装がこの仕組みを受け付けないため常に無効で、こちらは上書きできません。ENABLE_TOOL_SEARCH=falseを明示した場合も、結果としては同じく全ツールの説明文がセッション開始時にまとめて読み込まれます。この状態では、ツールごとの説明文がすべて最初からコンテキストに載るため、CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHを引き上げるとコンテキスト消費への影響がTool Search有効時より直接的に出ます。

MCPサーバーの説明文は2,048文字に収まる前提で書く

自分でMCPサーバーを実装している場合、この上限は「ユーザー側の設定」であると同時に「サーバー側の設計指針」でもあります。公式ドキュメントは、Tool Search(ツール検索)が有効な環境ではサーバーのinstructionsフィールドがより重要になると説明しています。Claudeがいつそのサーバーのツールを検索すべきかを判断する材料になるためです。

instructionsを書くときに含めるべき要素として、公式が挙げているのは次の3点です。

• そのサーバーのツールがどのカテゴリーのタスクを扱うか
• Claudeがいつそのツールを検索すべきか
• サーバーが提供する主要な機能

ユーザー環境の上限を前提にできない以上、サーバー開発者は既定の2,048文字に収まるよう説明文を書き、重要な情報ほど冒頭に置くのが安全策になります。ユーザー側が上限を引き上げていない限り、2,048文字を超えた部分はどのユーザーの環境でも一律に切り詰められるからです。プラグインに同梱したMCPサーバーを配布する場合も同じ制約を受けます。

説明文を書くときは、要点を先頭に置き、後半にいくほど省略されても実害の小さい補足情報を置く順番を優先します。「このツールは何をするか」「いつ呼ぶべきか」「主要な引数の意味」を最初の数百文字に詰め込み、エラーハンドリングの細かい注意点や稀なエッジケースの説明は後半に回します。2,048文字ちょうどで機械的に切られるため、文の途中で説明が終わっても不自然に見えない書き方を意識しておくと、切り詰めの影響を受けにくくなります。

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHが追加される前は、この上限は固定の2,048文字で変更する手段がありませんでした。長い説明文を持つサーバーの開発者は、上限に収まるよう文章を削るしかなく、ユーザー側から上限を緩和する選択肢はありませんでした。v2.1.280以降は、ユーザーが必要に応じて上限を引き上げられるようになった点が変化点です。

MAX_MCP_OUTPUT_TOKENSとの違い

似た名前の環境変数にMAX_MCP_OUTPUT_TOKENSがありますが、制御対象がまったく別です。

前者は「ツールをどう説明するか」、後者は「ツールを実行した結果がどれだけ返るか」を扱います。MCPサーバーが動かないと感じたら両方を疑う価値がありますが、症状は別です。説明文が途中で切れているように見えるなら前者、ツール呼び出し後に警告が出るなら後者を調整します。

いつ反映されるか

シェルのexportで設定した値は、Claude Codeが起動時に読み込むため、すでに起動しているセッションには反映されません。新しい値を使うには、そのセッションを終了してからclaudeを再起動します。

settings.jsonのenvキーに書いた値は扱いが異なります。ファイルを保存すると、実行中のセッションにも新しい値・変更した値が反映されます。ただしOpenTelemetryのようにセッション開始時に一度だけ変数を読む機能は、次にclaudeを起動するまで古い値のままです。CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHはこの例外に含まれていないため、settings.jsonを保存すれば実行中のセッションでも新しい上限が適用されると考えられます。

よくあるつまずき

• 数値以外を指定して無視される: "4096文字"のような単位付き文字列や小数は無効値として扱われ、既定の2,048文字に戻ります。プレーンな数字だけを渡します
• v2.1.280未満では効かない: この変数はv2.1.280以降が対象です。claude --versionで確認し、古い場合はアップデートしてから設定します。バージョンアップ後もMCPサーバーに接続できない場合の切り分け手順は別記事にまとめています
• シェルとsettings.jsonの二重設定: 両方に値を書くと、settings.jsonのenvブロックの値がシェルの値を上書きします。意図と違う値が効いていると感じたら、まずsettings.jsonを確認します
• 上限を上げてもコンテキストは無限に増やせない: サーバー数が多い環境では、Tool Searchによってツール定義自体は必要になるまで遅延読み込みされます。ただし読み込まれた説明文・指示が長ければ、その分だけコンテキストを消費する点は変わりません
• サーバーごとに個別の上限は設定できない: CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHはセッション内の全MCPサーバーに一律で適用される値で、特定のサーバーだけ上限を変える設定は公式ドキュメントに記載がありません。MAX_MCP_OUTPUT_TOKENSにはツール単位で上限を上書きするanthropic/maxResultSizeCharsアノテーションがありますが、説明文の文字数上限には同等の仕組みはありません

まとめ

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHは、MCPツール説明文とサーバー指示の既定2,048文字の切り詰め上限を変える環境変数で、v2.1.280以降で利用できます。長い説明文を持つサーバーを使っていて情報が欠けていると感じたユーザーは値を上げ、MCPサーバーを開発する側は既定値に収まる説明文を書くのが基本方針になります。

設定する場所は用途で選びます。今すぐ試すだけならシェルのexport、自分の全プロジェクトで恒久化するなら~/.claude/settings.json、チームで統一するなら.claude/settings.json、組織全体で強制するならManaged settingsです。MAX_MCP_OUTPUT_TOKENSとは制御対象がまったく異なるため、説明文が切れているのか実行結果が大きすぎるのかを見極めてから、どちらを調整するか判断します。