Claude CodeのMCPツール名が128文字を超えたときの対処

MCPサーバーに接続しているのに、特定のツールだけをClaudeが呼べない。/mcpには一覧に出ているのに使われない。そのツールの完全名が128文字を超えている可能性があります。

Claude Codeは、mcp__<サーバー名>__<ツール名>という完全名が128文字を超えたMCPツールを、Claudeへ送るツール一覧から外します。同じサーバーのほかのツールは動き続けます。デバッグログにはTool "mcp__<server>__<tool>" is not sent to Claudeという行が残ります。

症状は「ツールが呼ばれない」だけで、エラー画面は出ない

Claude Codeの現行の挙動では、長すぎるツールが原因でセッションが止まることはありません。送信から除外されるだけなので、画面にはエラーが出ず、Claudeがそのツールの存在を知らないまま会話が進みます。

手がかりは2か所にあります。

• /mcpを開いてツールを選ぶと、完全名(mcp__<server>__<tool>)が確認できます
• claude --debugで起動したセッションでは、~/.claude/debug/<session-id>.txtに次の行が書かれます

Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128

<N>には実際の文字数が入ります。128を何文字超えているかが分かるので、削る量の見積もりにそのまま使えます。

v2.1.292より前は全リクエストが400で落ちていた

v2.1.292より前のClaude Codeは、長い名前のツールもそのまま送っていました。APIはそのツールを含むリクエストをすべて拒否し、次のエラーが出ました。

API Error: 400 ... tools.N.custom.name: String should have at most 128 characters

つまり1本の長いツールが原因で、ほかのツールを使う依頼も、ツールと無関係な雑談も通りません。Nはツール配列の位置を示すだけで、どのツールかは名前では分かりません。

古い版で上のエラーが出ているなら、まずclaude updateで更新します。更新後は「全体が落ちる」状態から「該当ツールだけ使えない」状態に変わるので、次の節の手順で名前を縮めます。

128文字の内訳を数える

完全名の先頭は固定で、mcp__が5文字、サーバー名とツール名の間の__が2文字です。残りがサーバー名とツール名に割り当てられる計算になります。

この上限は接頭辞の文字数からの計算値です。プラグインの場合、mcp__plugin_の12文字と区切りの_、__が加わります。

手元のサーバーが危ないかどうかは、完全名をシェルで数えれば分かります。

printf '%s' 'mcp__analytics-database__run_query' | wc -c

この例は34文字なので余裕があります。128に近づくのは、サーバー名が長く、ツール名にも説明的な語を詰めたサーバーです。たとえばmcp__enterprise-customer-analytics-database__のような接頭辞に、get_monthly_active_users_by_region_and_plan_typeのようなツール名が続いても、合計は45文字+48文字の93文字で、まだ128には届きません。ここにさらに長い説明語が加わった名前が、上限に近づく目安です。

サーバー名を短くして直す

自分の設定に追加したサーバーなら、設定側の名前を縮めるのが最短です。サーバー名は完全名の接頭辞に入るので、analytics-databaseをdbにすれば16文字減ります。

claude mcp remove analytics-database
claude mcp add --transport http db https://mcp.example.com/mcp

URLは例です。stdioサーバーなら追加時のコマンド部分を、元の設定と同じものに置き換えてください。スコープ(local・project・user)も元と揃えないと、別の場所に重複して残ります。

ツール名そのものが長い場合は、サーバーの作者に短縮を依頼するか、自分で保守しているサーバーなら名前を変更します。ツール名を決めるのはサーバーの実装側なので、Claude Code側の設定で個別のツール名だけを短くすることはできません。

名前を変えたら、旧名を参照している設定を直す

サーバー名を変えると、旧名で書いた設定は一致しなくなります。見落とすと、許可していたはずのツールがまた確認を求めたり、フックが静かに動かなくなったりします。

直す場所は主に2つです。

• 権限ルール: mcp__analytics-database__*をmcp__db__*に書き換えます。サーバー全体ならmcp__dbでも指定できます
• hookのmatcher: mcp__analytics-database__.*をmcp__db__.*にします。hooksでは.*が必須で、mcp__dbだけのmatcherは完全一致の文字列として扱われ、どのツールにも一致しません

{
  "permissions": {
    "allow": ["mcp__db__*"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__db__.*",
        "hooks": [{ "type": "command", "command": "./audit.sh" }]
      }
    ]
  }
}

権限ルールとhook matcherでワイルドカードの書き方が違う点に注意します。権限は__*、hookは正規表現の__.*です。コピーして置換するときに片方へ混ぜないようにします。

新しい名前に.やスペースを使う場合、権限ルールではそれらが_に置き換わった形で書く必要があります。my.serverとして設定したサーバーならmcp__my_server__*です。短縮のついでにドットを含む名前へ変えるなら、この規則も効きます。サーバー名に__を含めるのは避けるのが無難です。

設定ファイルを置換したら、/mcpで新しい完全名を開き、権限ルールと文字列が一致しているかを目で確かめます。

プラグイン同梱のサーバーは自分では縮めにくい

プラグインが同梱するMCPサーバーのツールは、完全名にプラグイン名とサーバーキーの両方が入ります。形はmcp__plugin_<plugin-name>_<server-name>__<tool-name>で、A-Z・a-z・0-9・_・-以外の文字は_に置き換わります。

my-pluginに入ったdatabase-toolsサーバーのqueryツールなら、完全名はmcp__plugin_my-plugin_database-tools__queryで、43文字です。この名前が権限ルールやhook matcherで使う形でもあります。

プラグインの完全名を使う場面では、裸のサーバーキーで書いたmatcher(mcp__database-tools__.*など)は同梱サーバーに対して一度も発火しません。名前の長さを調べるときも、権限やhookを書くときも、プラグイン名を含む完全形を基準にします。

プラグインの場合、プラグイン名もサーバー名も作者が決めているので、利用者が設定で縮める余地はありません。上限を超えるツールが出たら、プラグインの保守者にサーバー名かツール名の短縮を依頼する流れになります。自社でプラグインを配布する側なら、プラグイン名の分だけ予算が減ることを前提に、サーバーキーとツール名を短く設計します。

長さの上限はほかの名前上限と別物

ツール名まわりの上限は複数あり、エラーも別です。

ツール定義の長さと履歴の長さでは見る場所が違います。MCP仕様が許す文字種と、Claude APIが受け付ける範囲のずれはMCPツール名の命名規則で、日本語名が弾かれる理由はClaudeツール名に使える文字で扱っています。

同じ「ツールが見えない」症状でも、ツール数が多すぎて定義が圧迫される場合は別の問題です。MCPのツール定義とコンテキスト圧迫と切り分けてください。

複数のツールをまとめて数える

サーバーにツールが何十個もあると、1本ずつ数えるのは現実的ではありません。/mcpで見た完全名をファイルに書き出し、128文字を超える行だけを拾います。

# names.txt に完全名を1行ずつ書く
awk '{ if (length($0) > 128) print length($0), $0 }' names.txt

出力が空なら、どのツールも上限に収まっています。行頭の数字は完全名の全長なので、その数から128を引いた値が削る量です。

サーバーを作る側の名前設計

自分でMCPサーバーを保守しているなら、利用者の設定ではなく作る側で余裕を持たせるのが根本的な対策です。利用者はclaude mcp addで好きな名前を付けられますが、プラグインで配布すると名前を選べません。

• サーバーキーは10文字前後までに収め、役割が分かる短い語にします
• ツール名は動詞と対象の2語程度にし、条件や出力形式はdescriptionに書きます
• 区切りは_か-に揃えます。.は権限ルールで_に置き換わり、書き間違いのもとになります

ツール名に条件を詰め込む設計は、名前を長くするうえに、似た名前のツールが並んで選択を迷わせます。説明文にも別の上限があるので、名前から説明文へ逃がす場合はMCPツール説明文の文字数上限も併せて確認します。

切り分けの順番

Claudeが特定のMCPツールを呼べないときは、次の順で確認すると早く絞れます。

上のどれにも当てはまらないときは、ツールが無効化されていないか、サーバーが接続状態かを/mcpで見直します。

よくある質問

名前の長さはバイトと文字のどちらで数えますか

ドキュメントは「128 characters」と書いており、バイト数とは書いていません。英数字・_・-だけの名前なら文字数とバイト数は一致するので、実害は出ません。

長いツールだけ外れるなら、気づかなくても問題ありませんか

そのツールの機能が使えないままになります。画面にエラーが出ないので、MCPサーバーを追加した直後は、/mcpで想定したツールが並んでいるかを一度確かめておくと安全です。