MCPツール名の命名規則とサーバー間衝突の防ぎ方

MCPのツール名は1〜128文字、使える記号は3つだけ

MCP(Model Context Protocol)の現行仕様は、ツール名の書式を明確に規定しています。大文字小文字を区別し、使える文字は英数字とアンダースコア(_)、ハイフン(-)、ドット(.)のみです。スペースやカンマなど、これ以外の記号は含めるべきではありません。

仕様書が有効な名前の例に挙げるのはgetUser、DATA_EXPORT_v2、admin.tools.listの3つです。ドットを使ったadmin.tools.listのような階層的な命名も許容されます。この書式ルールは「SHOULD」(推奨)として書かれており、MUST(必須)ではありません。

この規定はSEP-986という提案が起点になりました。SEPは仕様変更提案(Specification Enhancement Proposal)の略で、プロセスの全体像はMCPのSEPプロセスにまとめています。

SEP-986が提案した書式と、現行仕様で変わった点

SEP-986「Specify Format for Tool Names」は2025年7月16日にkentcdodds氏が提出しました。Standards Trackとして、最終的にFinalステータスに達しています。提案の動機はシンプルです。ツール名の書式が未規定だったため、実装ごとに区切り文字や大文字小文字の扱いがばらつき、ツール呼び出しのミス、ドキュメント作成や自動化の手間につながっていました。

提案が掲げた狙いは4つです。

• ツール名をクライアント間で予測可能・相互運用可能にする
• スラッシュやドットを使った階層的な名前空間分けを可能にする
• 人間が読める名前と機械生成された名前の両方に対応する
• 有効なユースケースを不必要に妨げる制限を避ける

提案文書の元の内容と、現行仕様(2026-07-28)に実際に反映された内容には、見落としやすい差分があります。

SEPはFinal時点の設計を残した記録で、Final後の仕様変更はSEP本文に反映されません。仕様を引くときは現行のserver/toolsを見ます。プロトコル自体の改訂履歴はMCP仕様のバージョン履歴で扱っています。

なぜスペースとカンマを禁止したのか

SEP-986のRationale(論拠)節は、書式を決める際の判断基準も記録しています。提案の出発点は、既存の実装がすでにばらばらの区切り文字・大文字小文字の使い方・文字集合を採用していたという現状でした。lower-kebab-case(小文字とハイフン)は一般的な慣習の1つでした。ただ、多くのツールやクライアントは、名前空間分けや可読性のために大文字・アンダースコア・ドット・スラッシュも使っていました。そこで提案は、特定の1つの慣習に絞り込むのではなく、複数の慣習を横断的に許容する方向を選んでいます。

一方でスペースとカンマは明確に除外されました。Rationaleの説明は「パースの問題と曖昧さを避けるため」の一文です。区切り文字として使われやすい記号を名前に含めると、名前の切れ目を機械的に判別しにくくなります。

文字数の上限は「ほとんどの用途には十分に余裕があり、乱用は防げる」水準として設定されています。セキュリティ面では、書式を標準化すること自体が新たなリスクを持ち込むことはないとSEPは明記しています。

Rationaleには、もう1つ見逃せない一文があります。許可文字のパターンは「VS CodeやClaudeなど主要なクライアントで使われているパターンに基づく」とされています。次の節で見るとおり、この「Claude」の実際の定義は、MCP仕様より狭い正規表現です。

同じ名前でも、MCP仕様は通りClaude APIは通らないことがある

Claude CodeはMCPサーバーのツールをAPIリクエストに含めて送ります。そのAPIのツール定義のnameには、ドキュメントの表に正規表現が書かれています。^[a-zA-Z0-9_-]{1,128}$です。MCP仕様の許可文字からドットを引いた形で、長さの上限は128文字で揃っています。

3つの規則を同じ名前に当てると、結果は次のようにずれます。完全名が128文字を超えたときのClaude Codeの挙動はMCPツール名が128文字を超えたときの対処にあります。

import re
spec = re.compile(r'^[A-Za-z0-9_.-]{1,128}$')   # MCP 2026-07-28
sep  = re.compile(r'^[A-Za-z0-9_./-]{1,64}$')   # SEP-986 の提案文面
api  = re.compile(r'^[a-zA-Z0-9_-]{1,128}$')    # Claude API の name
 
for n in ["getUser", "admin.tools.list", "user-profile/update",
          "search documents", "a" * 65, "a" * 129]:
    print(n, bool(sep.match(n)), bool(spec.match(n)), bool(api.match(n)))

name                  SEP-986  MCP 2026-07-28  Claude API
getUser               True     True            True
admin.tools.list      True     True            False
user-profile/update   True     False           False
search documents      False    False           False
(65 chars)            False    True            True
(129 chars)           False    False           False

注目するのはadmin.tools.listの行です。MCP仕様が有効例として掲げる名前なのに、APIの正規表現には合いません。仕様書の例に従ってドットで階層を表したサーバーは、仕様の上では適合していても、API側の定義とは噛み合いません。この組み合わせでクライアントがどう振る舞うかは、MCP仕様にもAPIの表にも書かれていないので、クライアントの実装に委ねられています。

Claude Codeのドキュメントには、近い性質の置き換え規則があります。プラグイン経由のMCPサーバーでは、呼び出し名がmcp__plugin_<プラグイン名>_<サーバー名>__<ツール名>になり、A-Z・a-z・0-9・_・-以外の文字は_に置き換えられます。ドキュメントの規則どおりなら、プラグイン経由の呼び出し名はAPIの正規表現と同じ文字の範囲に収まります。

ドットを避けて_か-で区切れば、MCP仕様とAPIの両方の正規表現に合います。階層を表したいならadmin_tools_listのような書き方です。スラッシュはSEPの文面にだけ残る記号なので、提案書を頼りに命名すると外れやすい点にも注意が要ります。

Claude Codeでの実際の呼び出し名と、権限・フックでの書き方

Claude Codeは、MCPツールをmcp__<サーバー名>__<ツール名>の形で扱います。権限設定の例にはmcp__puppeteer__puppeteer_navigateが載っており、サーバー単位ならmcp__puppeteer、ワイルドカードならmcp__puppeteer__*と書けます。

フックのmatcherでも同じ名前を使います。mcp__memory__create_entitiesのようにサーバー名とツール名をつなぎ、サーバーの全ツールを対象にするならmcp__memory__.*と書きます。ドキュメントは.*が必須だと明記しています。mcp__memoryだけのmatcherは完全一致の文字列として比較され、どのツールにも一致しません。

この命名には副産物があります。サーバー名が接頭辞に入るので、2つのサーバーがsearchを公開しても、Claude Code上の呼び出し名はmcp__a__searchとmcp__b__searchに分かれます。次の節で扱う衝突は、クライアントが接頭辞を付ければ表面上は消えます。

一意性は「サーバー単位」— 複数サーバーを束ねるクライアントが踏む落とし穴

現行仕様が明記するもう1つの重要な点は、ツール名の一意性が単一サーバーの中でのみ保証されるということです。仕様書の注記は次のように述べています。

ツール名の一意性はサーバー単位のスコープです。複数サーバーからツールを集約するクライアントやプロキシは名前の衝突(たとえば2つのサーバーがそれぞれsearchという名前のツールを公開している場合)に遭遇する可能性があります。そのため、サーバー識別子をツール名にプレフィックスするなどのディスアンビギュエーション(名前衝突解消)戦略を実装すべきです。

接続した2つのサーバーが同じsearchやget_statusのような一般的な名前のツールを公開していれば、クライアント側で区別する仕組みが必要になります。

仕様が示す対策は、サーバー識別子をツール名の前に付けるプレフィックス方式です。ただし注記はもう1点、見落としやすい制約も添えています。serverInfoに含まれるサーバーのnameフィールドは、サーバー間で一意であることが保証されておらず、ディスアンビギュエーションの根拠として頼るべきではないとされています。

つまり「サーバーが名乗る名前を頭に付ければ安全」という単純な実装では、サーバー名自体が別のサーバーと重複するケースを取りこぼします。Claude Codeのmcp__<サーバー名>__の部分は、claude mcp add <name> <url>で自分が付ける名前です。サーバー自身の申告に頼らず、接続する側が名前を割り当てる形なので、サーバー同士の名前の重複に左右されません。

名前が仕様に沿っているかを見分ける

命名規則を読んだだけでは、実際にどの名前がアウトかを判断しづらいものです。同じ意味の名前でも、記号1つで仕様の範囲を外れます。

大文字小文字を区別する点も見落としやすい要素です。仕様は大文字小文字の区別を推奨しているので、getUserとgetuserは別のツール名として扱うのが基本です。1つのサーバー内では、getUser系とスネークケースが混在しないよう、大文字小文字の使い方も揃えておくと取り違えを防げます。

既存のツール名を変更するときの配慮

サーバーを運用しながら命名規則に合わせてツール名を変更する場面では、呼び出し側のクライアントやエージェントが古い名前を前提に動いていることがあります。SEP-986の提案書が挙げる移行時の配慮は3点です。

これらはSEP提案書に書かれた推奨であり、現行の仕様書本体に同一の文言があるわけではありません。ただし、後方互換性を壊さずに命名規則へ追随するための実務的な指針として参考になります。急に名前を変更してツール呼び出しを壊すより、エイリアスを一定期間残す方が、接続先のクライアント側の実装を待つ猶予を作れます。

SEP提案書はさらに、参照実装のイメージとしてMCPコアライブラリ側でツール登録時にこの検証ルールを強制する仕組みにも触れています。サーバー実装者が手作業で命名規則を確認するのではなく、SDKやフレームワークのレイヤーで機械的に弾く方が、規則からの逸脱を防ぎやすいという発想です。

新しくサーバーを作るときの命名の目安

Claudeから使われるサーバーを作るなら、ツール名は英数字・アンダースコア・ハイフンの範囲に収めるのが無難です。

同じ名前が1つのサーバーに2つ入らないようにするのは、仕様の「一意」に沿うための最低条件です。ほかのサーバーとの衝突は接続する側が接頭辞で解くので、searchのような一般的な名前を避ける必要まではありません。個々のツール定義の残りのフィールド(inputSchemaやannotationsなど)はMCPのTools仕様を読み解くで扱っています。

まとめ — 既存のドット名は別名を足して移す

ドットを使ったツール名がすでに動いているサーバーは、古い名前をエイリアスで残したまま別名を足すと、呼び出し側を壊さずに移せます。複数のサーバーを束ねる実装は、サーバー自身のnameでなく、接続側で付けた識別子を接頭辞にします。MCPの基礎から確認したい場合はMCPとはを先に読むと文脈がつかみやすくなります。