Claude Media
MAX_MCP_OUTPUT_TOKENSとは — MCPツール出力の上限を変える環境変数
Claude CodeMCPTips

MAX_MCP_OUTPUT_TOKENSとは — MCPツール出力の上限を変える環境変数

MAX_MCP_OUTPUT_TOKENSは、MCPツールが返す結果の最大トークン数を決める環境変数です。既定値・警告との違い・サーバー側の個別上限との使い分けをまとめます。

読了目安 約8分

MAX_MCP_OUTPUT_TOKENSは、MCP(Model Context Protocol)ツールが1回の呼び出しで返せる出力の最大トークン数を決める環境変数です。既定値は25,000トークンで、10,000トークンを超えると警告が表示されます。データベースやファイルシステム系のMCPサーバーは応答が数万トークンに達することがあり、既定のままだと結果が切り詰められたり警告が繰り返し出たりします。この変数が何を変え、何を変えないのか、そしてサーバー側の設定とどう使い分けるかを見ていきます。

MAX_MCP_OUTPUT_TOKENSが変えるもの

この変数が制御するのは、MCPツール応答のうち独自の上限を宣言していないものの最大トークン数です。既定は25,000トークンで、export MAX_MCP_OUTPUT_TOKENS=50000のように上書きします。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

警告のしきい値(10,000トークン)と実際の上限(既定25,000トークン)は別物です。警告は「そろそろ大きい」というサインで、この変数を変えても警告のしきい値そのものは動きません。動くのは、警告の先にある「ここで打ち切る」という上限側だけです。

対象範囲にも条件があります。テキスト出力はこの変数の対象ですが、ツールが anthropic/maxResultSizeChars を宣言している場合、そのツールのテキストだけは宣言側の文字数上限が優先されます。一方で画像を返すツールは、anthropic/maxResultSizeChars の有無にかかわらず常にこの変数の対象です。画像で上限を回避したいときの逃げ道はこの変数を上げる以外にありません。

上限を超えるとどうなるか

しきい値を超えた結果は、会話に流し込まれる代わりにディスクへ保存され、会話には保存先のファイル参照だけが渡ります。ツール呼び出しそのものは失敗にならず、Claudeは参照されたファイルを別途読みに行くことで内容を確認できます。ただし1回のツール呼び出しの結果を素直に読み進める前提で会話が進んでいる場合、この切り替わりに気づかず「情報が抜け落ちた」と感じることがあります。大きな出力を返すMCPツールを使うときは、警告が出た時点で結果がそのまま会話に載っているのか、ファイル参照に切り替わっているのかを一度確認しておくと混乱を避けられます。

サーバー側の個別上限(anthropic/maxResultSizeChars)との使い分け

MCPサーバーを自作・カスタマイズできる立場かどうかで、取れる手段が変わります。

立場手段効果
MCPサーバーの利用者(設定変更のみ)手段MAX_MCP_OUTPUT_TOKENS を上げる効果対象範囲の全ツールの上限が一律で上がる
MCPサーバーの実装者手段tools/list の _meta に anthropic/maxResultSizeChars を宣言効果そのツールだけ最大500,000文字まで個別に引き上げ

サーバー側の宣言はテキスト出力に対して環境変数より優先され、宣言済みのツールなら利用者側はMAX_MCP_OUTPUT_TOKENSを触らなくても大きな結果を受け取れます。宣言がないツールの結果がしきい値を超えると、応答はディスクへ保存され、会話にはファイル参照だけが渡ります。データベースのスキーマ全体やファイルツリーのように、本質的に大きくなるが必要な出力を返すツールほど、この宣言の恩恵が大きくなります。

自分が使っているMCPサーバーを制御できないなら、選択肢はMAX_MCP_OUTPUT_TOKENSを上げるか、開発元にanthropic/maxResultSizeCharsの宣言かページネーションの追加を依頼するかの2つです。接続や認証を含むMCPサーバー追加の手順全体はClaude Code MCP設定ガイドにまとめています。

anthropic/maxResultSizeCharsはもともとの仕組みではなく、後から追加された個別調整の手段です。データベーススキーマのような本質的に大きい結果を持つツールの需要に応える形で、v2.1.91で導入されました。導入直後のv2.1.98では、この宣言を付けても一部のツールでトークンベースの永続化レイヤーを回避できていない不具合が見つかり、修正されています。個別ツールの上限を宣言する仕組み自体は比較的新しい機能なので、古いMCPサーバー実装では対応していないことがあります。

手元の設定を確認する

上限を上げたつもりでも実際には反映されていない、という状況を避けるには、設定後にいくつかの箇所を確認しておくと確実です。

  • env | grep MAX_MCP_OUTPUT_TOKENS(PowerShellならGet-ChildItem Env:MAX_MCP_OUTPUT_TOKENS)でシェル側の値を確認する
  • /statusで、現在のセッションにどの設定ソースの値が有効になっているかを確認する

シェルのexportとsettings.jsonのenvブロックを両方使っている場合の優先順位の切り分け方は、後述の「値を変えても警告が消えないときに確認すること」でまとめて扱います。設定ファイルへの書き方全般はClaude Code環境変数リファレンスを参照してください。

大きな出力を返しやすいMCPサーバーの傾向

すべてのMCPツールがこの上限に引っかかるわけではありません。典型的に出力が大きくなりやすいのは、データベースへのクエリー結果をそのまま返すツール、ファイルツリーやリポジトリ全体を列挙するツール、ログやモニタリングデータを集計せず生のまま返すツールです。逆に、単一のレコードを取得するAPI呼び出しや、要約済みの結果を返すよう設計されたツールでは、警告に遭遇する機会はあまりありません。自分がよく使うMCPサーバーがどちらの傾向かを把握しておくと、警告が出たときに「設定の問題」なのか「そのツールの性質上避けられない」のかを切り分けやすくなります。用途別のMCPサーバーの選び方はおすすめMCPサーバー10選にまとめています。

なお、この変数が働くのはMCPツールとの通信段階です。Claude Code自体がAnthropic API・Amazon Bedrock・Vertex AIのどの経路でモデルにつながっているかとは別のレイヤーなので、接続先を切り替える設定とは独立して機能します。

似た名前の環境変数と混同しない

Claude Codeには「出力の上限」を扱う変数が複数あり、対象が違います。

環境変数上限をかける対象既定値
MAX_MCP_OUTPUT_TOKENS上限をかける対象MCPツールの応答既定値25,000トークン
CLAUDE_CODE_MAX_OUTPUT_TOKENS上限をかける対象Claudeモデル自体の出力(ほとんどのリクエスト)既定値モデルにより変動
BASH_MAX_OUTPUT_LENGTH上限をかける対象bashコマンドの出力を読み戻す文字数既定値30,000文字(最大150,000)

3つとも「上限」という言葉が付くため名前だけでは区別しづらいですが、効く場所はそれぞれ独立しています。MCPサーバーからの応答が切り詰められて困っているときにCLAUDE_CODE_MAX_OUTPUT_TOKENSを上げても効果はありません。逆にモデルの生成が途中で止まる問題はMAX_MCP_OUTPUT_TOKENSでは直りません。

上限を上げる前に確認したいこと

MAX_MCP_OUTPUT_TOKENSを上げると警告や切り詰めは減りますが、代わりに会話のコンテキストウィンドウを圧迫します。大きな結果をそのまま毎回コンテキストへ流し込む構成は、上限を上げても持続可能とは限りません。

  • 特定のMCPサーバーで頻繁に警告が出るなら、まずanthropic/maxResultSizeCharsの宣言かページネーション対応をサーバー開発元に相談する方が根本解決に近いことがあります
  • 上限を上げる対応は、開発元に依頼できない外部サーバーを使っていて、かつ大きな結果自体が必要なときの現実的な選択肢です
  • 出力が大きくなりやすいサーバーの傾向を踏まえたうえで、そもそも用途に合ったMCPサーバーを選び直すという選択肢もあります

環境変数をどこに書くか(シェルかsettings.jsonのenvブロックか)や、書いたのに効かないときの切り分け手順はClaude Code環境変数リファレンスにまとめています。

値を変えても警告が消えないときに確認すること

MAX_MCP_OUTPUT_TOKENSを上げたはずなのに同じ症状が続く場合、いくつか切り分けポイントがあります。

  • 対象のツールがanthropic/maxResultSizeCharsを宣言していないか: 宣言済みのツールはテキスト出力についてこの変数を無視し、宣言側の文字数上限に従います。宣言の有無はサーバーの実装次第なので、利用者側からは挙動でしか判断できません
  • 画像出力ではないか: 画像コンテンツは常にこの変数の対象です。文字数の宣言があっても画像には効きません
  • 新しいセッションで反映されているか: 環境変数は起動時に読み込まれるため、値を変えたあとにclaudeを再起動していないと古い値のまま動いていることがあります
  • 設定ファイルの優先順位で上書きされていないか: シェルのexportとsettings.jsonのenvブロックの両方に値を書いている場合、意図しない方が優先されている可能性があります

これらを確認しても解決しない場合は、対象のMCPサーバー自体の実装(タイムアウトやページネーションの有無)を疑う方が早いことがあります。

よくある質問

MAX_MCP_OUTPUT_TOKENSを設定してもMCPツールの出力が切り詰められるのはなぜですか

対象のツールがanthropic/maxResultSizeCharsを宣言している場合、テキスト出力はこの変数ではなく宣言側の文字数上限に従います。ツールの実装側の上限を確認してください。

画像を返すMCPツールにも同じ上限がかかりますか

かかります。画像コンテンツはanthropic/maxResultSizeCharsの宣言の有無にかかわらず、常にMAX_MCP_OUTPUT_TOKENSの対象です。

10,000トークンの警告を消すことはできますか

警告のしきい値自体は固定で、MAX_MCP_OUTPUT_TOKENSを変えても動きません。警告を避けたいなら、出力そのものを減らす方向で対応します。

settings.jsonに書いても有効ですか

envブロックに書けば、シェルで都度exportしなくても有効になります。設定ファイルの優先度は、ユーザー設定 → プロジェクト設定 → ローカル設定の順に高くなり、同じキーが複数箇所にあれば優先度の高い側が使われます。

上限を極端に大きくしても問題ありませんか

サーバー側の宣言による個別上限は500,000文字が上限です。MAX_MCP_OUTPUT_TOKENS自体に明示された上限はありませんが、大きくするほど1回の応答がコンテキストウィンドウを圧迫する点は変わりません。

しきい値を超えた結果はどこに保存されますか

anthropic/maxResultSizeCharsを宣言していないツールの結果がしきい値を超えると、ローカルにファイルとして保存され、会話にはその参照だけが渡ります。保存先のパスは公式ドキュメントに明記されていません。

CLAUDE_CODE_MAX_OUTPUT_TOKENSと同時に設定できますか

できます。片方はMCPツールの応答、もう片方はモデル自体の出力という別の対象を制御するため、干渉しません。同時に大きくすると、それぞれが個別にコンテキストウィンドウを圧迫する点だけ意識しておきます。

まとめ

MAX_MCP_OUTPUT_TOKENSはMCPツール応答のトークン上限を既定25,000から引き上げる環境変数で、10,000トークンの警告しきい値とは別物です。テキスト出力はツール側がanthropic/maxResultSizeCharsを宣言していればそちらが優先され、画像出力は常にこの変数の対象になります。自分で変更できないサーバーの出力が大きいときの調整弁として使い、根本的な解決はサーバー開発元への改善依頼と併用するのが現実的です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →