公開日：2026/09/24 01:59 最終更新日：2026/09/25 16:30

Claude CodeのMCPツール説明文に2,048字上限、実際のサーバーで測ってみた

Xでシェア facebookでシェア LINEでシェア

AI実用ラボ

複数のMCPサーバーをClaude Codeに繋いでいると、起動のたびに「なんとなく重い」「コンテキストを食っていそう」と感じることがある。

でも実際どれくらいのコストなのか、自分のMCPサーバーが危険水域にいるのかどうかを、体感ではなく数字で確認したことがある人は少ないはずだ。

Claude Code v2.1.280（2026年9月22日リリース）で、MCPツールの説明文(description)とサーバーの指示文(instructions)に既にかかっていた2,048文字の上限を、環境変数で変更できるようになった。この記事では公式の変更点と、実際に運用しているMCPサーバーのツール定義をPython標準ライブラリだけで実測した結果を紹介する。TL;DR

MCPサーバーをいくつも繋いでるんですけど、これって説明文を書けば書くほど重くなるんですか？

感覚ではなく、実際に測ってみましょう。うちで使っているMCPサーバーを例に、公式の上限と実測値を並べて見ていきます。

この記事でできること

Claude Code v2.1.280で追加されたMCPツール説明文の文字数上限と、変更する環境変数の正確な仕様が分かる
自分のMCPサーバーのツール定義がどれくらいの文字数か、Python標準ライブラリだけで測る方法が分かる
上限に近づいたときの現実的な対策（接続スコープを絞る、--strict-mcp-configを使う）が分かる

対象読者

Claude CodeにMCPサーバーを複数接続している人
自作MCPサーバーのdescriptionフィールドをどこまで詳しく書いてよいか迷っている人
「なんとなく重い」を数字で確認したい人

確認環境・確認日

確認日: 2026年9月23日
Claude Code CLI: 2.1.267
実測対象: MCPツール定義6件

背景：説明文の上限は今回新しく生まれたわけではない

Claude Codeの公式チェンジログ（2026年9月22日付、v2.1.280）には次の記載がある。

Added CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to change the 2,048-character cap on MCP tool descriptions and server instructions for every MCP server in the session

日本語にすると「MCPツールの説明文とサーバーの指示文にかかっている2,048文字の上限を変更するための環境変数を追加した」という内容だ。

ポイントは、この2,048文字という上限そのものはv2.1.280より前から存在していたと読める点。今回追加されたのは「上限を変える手段」であって、上限そのものが新設されたわけではない。

上限を超えた場合に具体的にエラーになるのか、黙って切り詰められるのかまでは、このチェンジログの一文だけでは分からない。「cap（上限）」という言葉づかいからは値が切り詰められる可能性が高そうだが、断定できる記載は見つからなかったため、本記事でも断定しない。

似たような名前の制限に、MCPツールの実行結果（出力）に対する上限もある。こちらはMAX_MCP_OUTPUT_TOKENS環境変数で調整でき、デフォルトは25,000トークン、10,000トークンを超えると警告が出る。「ツールの説明文」と「ツールの実行結果」は別物なので、混同しないようにしたい。

説明文の上限と、実行結果の上限って、別々にあるんですね。

はい。説明文は“ツールの取扱説明書”、実行結果の上限は“実際に返ってきたデータ”の話です。今回扱うのは前者です。

何が便利なのか：見えていなかったコストが数字になる

	今まで	今回の方法
MCPサーバーが重いかどうかの判断	なんとなくの体感	実際の文字数で判断できる
上限に近いかどうかの確認	分からない	自分のツール定義を測って確認できる
対策の選び方	とりあえず接続を減らす	何が大きいかを見てから絞り込める

必要なもの

Python 3（標準ライブラリのjsonとlenだけで完結する。バージョンは問わない）
自分が使っているMCPサーバーのツール定義（JSON形式。取得できなければ実装コード上のdescription文字列を直接コピーしてもよい）

全体像

手元のMCPサーバーのツール定義（description、parameters）をJSONとして用意する
Pythonでdescriptionの文字数と、定義全体の文字数を数える
2,048文字に近いツールがあれば、そこから対策を検討する

実際にやってみる：Tips MCPのツール定義を測る

MCPサーバーのツール6件を対象に、descriptionの長さを測定した。

方法は、各ツールのJSON Schema定義からdescription文字列を取り出し、Pythonのlen()で文字数を数えるだけだ。

import json

def describe_length(tool_def: dict) -> dict:
    """MCPツール定義のdescription文字数と、定義全体の文字数を返す"""
    description = tool_def.get("description", "")
    full_json = json.dumps(tool_def, ensure_ascii=False)
    return {
        "name": tool_def.get("name"),
        "description_chars": len(description),
        "full_definition_chars": len(full_json),
    }

# tool_def には、MCPサーバーが返すツール定義(1件分のJSON)を入れる
# 例: {"name": "...", "description": "...", "parameters": {...}}

実測結果は次のとおりだった。Tips MCPサーバー全体には約19個のツールがあり、今回測れたのはその一部（サンプル）にすぎない。

ツール名	description文字数
get_article_settings	46
get_authored_article_detail	63
get_authored_articles	76
get_sales_history	76
update_article_draft	263
save_article_settings	685
6ツール合計	1,209

一番長いsave_article_settingsのdescriptionでも685文字で、2,048文字の上限にはまだ余裕がある。

ただし、このツールはparameters（入力スキーマ）を含めた定義全体をjson.dumps()すると2,665文字になる。2,048文字の上限はdescription/instructionsフィールドが対象で、parametersスキーマは対象外と読めるが、実際にセッションのコンテキストへ読み込まれる総量としては両方が合算される。

「上限に達していないから安心」ではなく、定義全体でどれくらいの量になっているかを見る方が実態に近い。

685文字なら余裕じゃないですか。

descriptionだけならそうですね。でもparameters込みだと2,665文字になる。ツール1個でこの量なので、10個20個と繋げば無視できない量になってきます。

なお、WebSearchで見つけた技術ブログに「84個のツールを複数のMCPサーバーから読み込んだ場合、最初のメッセージを処理する前に15,540トークンを消費した」という趣旨の計測例への言及があった。

公式発表ではなく一つの計測例なので断定材料としては扱わないが、「ツールの数が増えるほど負担も増える」という方向性は、今回の実測結果とも矛盾しない。

対策：接続するMCPサーバーを絞り込む

上限そのものに引っかかっていなくても、繋いでいるMCPサーバーの数や定義量を絞りたい場面はある。Claude Codeには、実際に確認できたところで次の手段がある。

1. --strict-mcp-configで読み込むサーバーを固定する

Claude Code CLI v2.1.267の`--help`では、次のように説明されている。

--strict-mcp-config   Only use MCP servers from --mcp-config,
                       ignoring all other MCP configurations

--mcp-configで指定したJSONファイルのMCPサーバーだけを使い、他の設定（ユーザー設定やプロジェクト設定にあるmcpServers）を無視する。両方ともclaudeコマンド自体に渡すトップレベルのフラグで、セッションを起動するときに指定する。

claude --mcp-config ./minimal-mcp.json --strict-mcp-config

普段使わないMCPサーバーがなんとなく全部繋がってしまっている、という状態を避けたいときに使う。

2. 接続スコープを分ける

MCPサーバーは、どの範囲で使うかによって設定の保存場所が変わる。project scopeは.mcp.jsonに保存されチームで共有され、local/user scopeは~/.claude.jsonに保存され個人用として全プロジェクトで使われる。

無関係なプロジェクトでも全部のMCPサーバーが毎回読み込まれている、という状態になっていないか、自分の~/.claude.jsonと各プロジェクトの.mcp.jsonを見直してみるとよい。

なんとなく繋いだままのMCPサーバー、結構あるかもしれません。

測ってから絞り込む、の順番が大事です。まず測って、重いものから見直すのが早いですよ。

エラー対処

Q. 自分のMCPサーバーのJSON定義がどこにあるか分からない

MCPサーバーを自分で実装している場合は、ツール登録部分のコード（description文字列を書いている箇所）を直接参照すればよい。外部提供のMCPサーバーなら、Claude Code側のツール一覧表示やサーバーのドキュメント・ソースコードから確認する。

Q. CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHを設定しても変わらない

この環境変数はv2.1.280以降で追加されたものです。まず`claude --version`でv2.1.280以降か確認してください。

Q. 上限を超えるとどんなエラーが出るのか知りたい

公式チェンジログの一文からは、超過時の具体的な挙動（エラーになるのか、切り詰められるのか）までは分からなかった。この記事では推測で断定せず、「上限（cap）」という表現から切り詰めの可能性が高いと考えられる、という書き方にとどめている。

注意点・制限事項

今回の実測はTips MCPサーバー約19ツールのうち6ツールのサンプルであり、全数調査ではない
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHはv2.1.280以降が対象
上限を超えた場合の具体的な挙動（エラー/切り詰め）は公式情報からは断定できない

早見表

項目	内容
上限の対象	MCPツールのdescription、サーバーのinstructions
デフォルト上限	2,048文字
変更する環境変数	CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH（v2.1.280以降）
別の上限（結果側）	MAX_MCP_OUTPUT_TOKENS（デフォルト25,000トークン、10,000トークン超で警告）
接続を絞るフラグ	--mcp-config + --strict-mcp-config
スコープ	project(.mcp.json) / local・user(~/.claude.json)