Claude Media
MCP Registryのバージョニングルール — 公開後は変更不可
MCP解説

MCP Registryのバージョニングルール — 公開後は変更不可

MCP Registryに公開したサーバーのバージョンはなぜ書き換えられないのか。文字列の書式ルールと、アグリゲーター側の並び替えロジックまで押さえます。

読了目安 約9分

MCP Registryに公開したサーバーのバージョンは、一度公開すると二度と書き換えられません。npmのパッケージ公開と同じ不変性のルールで、メタデータを直したいときも既存バージョンの上書きではなく、新しいバージョン文字列での再公開が必須になります。文字列の形式は自由ですが、セマンティックバージョニング(semver)から外れるほど、検索結果での並び順が不利になる設計です。

「バージョン」が指すものを先に区別する

MCP Registryのversionは、サーバーの公開ごとに一意でなければならない文字列です。このversionは、MCPプロトコル自体が持つバージョン(クライアントとサーバーがやり取りの規格を合わせるための日付形式の識別子)とは別物です。プロトコルバージョンはMCPの通信仕様そのものを指し、サーバーのversionは個々のサーバー実装のリリースを指します。両者を混同すると、server.jsonのversionを書き換えればプロトコルの互換性も変わると誤解しかねません。実際には無関係な2つの値です。

バージョン文字列の書式ルール

MCP Registryはsemverを推奨しますが、文字列の形式そのものは自由です。公開時にsemverとして解釈を試み、解釈できればソート対象・できなければ常に「latest」扱いになります。

例種別扱い
1.0.0種別セマンティックバージョン扱い推奨
2.1.3-alpha種別セマンティックプレリリース扱い推奨
2025.11.25種別日付形式(semver互換)扱い推奨
2025-06-18種別日付形式(非semver)扱い許可
v1.0種別プレフィックス付き扱い許可
^1.2.3 ~1.2.3 >=1.2.3 1.x 1.2.*種別バージョン範囲指定扱い禁止

範囲指定を禁止しているのは、バージョン文字列が「特定の1つの公開」を指す識別子であって、複数バージョンを束ねる表現ではないためです。^1.2.3のような範囲構文を許すと、どの公開を指しているのか一意に定まらなくなります。npmのpackage.jsonが依存関係の宣言に範囲構文を使うのとは役割が異なり、MCP Registryのversionは依存解決の入力ではなく、1回の公開を指すラベルだと考えると整理しやすくなります。

一度semverを使ったサーバーが、途中で非semver形式に切り替えると挙動が変わる点には注意が必要です。新しく公開したバージョンが本来のソート順ではもっと前に来るはずでも、非semverと判定された瞬間に自動的に「latest」として扱われます。意図せず古い番号を新しい番号として見せてしまう典型パターンです。

公開後の不変性が公開ワークフローに与える影響

server.jsonのバージョン文字列は、公開ごとに一意でなければなりません。一度公開したバージョンの中身(パッケージ識別子・説明文・環境変数の定義など)は、あとから直接編集できません。誤字を直したいだけでも、新しいバージョン文字列で丸ごと再公開する必要があります。

パッケージの実体を変えずにメタデータだけを更新したい場面は珍しくありません。説明文を整えた、環境変数の説明を追記した、といったケースです。この用途向けに公式が案内しているのが、セマンティックプレリリース版を使う方法です。

{
  "version": "1.2.3-1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": { "type": "stdio" }
    }
  ]
}

1.2.3-1のようなプレリリース表記であれば、実体のnpmパッケージは1.2.3のまま、MCP Registry側のメタデータだけを複数回公開し直せます。ただし注意点があります。プレリリース版は正規のバージョンより前にソートされるため、正規版1.2.3を先に公開してから1.2.3-1を後追いで公開すると、そのプレリリース版は「latest」にはなりません。メタデータ更新のためのプレリリース公開は、正規版を公開する前に済ませておく順序が安全です。

メタデータの中に独自の付加情報(_meta.io.modelcontextprotocol.registry/publisher-provided以下のフィールド)を持たせることもできますが、この領域には4KB(4096バイト)というサイズ上限があります。公開のたびにログや設定サンプルをまるごと詰め込むような使い方をすると、この上限に引っかかって公開自体が失敗します。独自メタデータは要点だけに絞る前提で設計してください。

公開したサーバーを消す・非公開にする方法はあるか

不変性は「上書きできない」だけでなく「消せない」も含みます。MCP Registryには、公開済みサーバーを削除・非公開化する手段が用意されていません。公式のGitHubリポジトリでは、この機能の要否について議論が続いている段階です。

つまり、公開に失敗したと気づいても、そのバージョンの記録は現状の仕様では削除できません。実務上の対処は「間違ったバージョンを放置し、正しい内容の新バージョンを公開してlatestを上書きする」以外にありません。テスト目的で本番のnamespaceに気軽に公開すると、消せない記録が積み上がることになるため、動作確認は別の名前空間や手元のRegistry互換API(セルフホスト)で済ませておくのが無難です。

なお、MCP Registryは現時点でpreview段階にあり、公式ドキュメントは全ページ冒頭で「General Availability前に破壊的変更やデータリセットが起きうる」と明記しています。ここまで述べてきた「公開後は変更不可・削除不可」というルールも、この前提の上に成り立っています。GA前にRegistry側の運用方針そのものが変わる可能性はあるため、恒久仕様として断定はできません。

サーバーバージョンと配下パッケージバージョンの揃え方

サーバーのversionと、packages配列内の各パッケージのversionは別のフィールドですが、揃えておくのが公式のベストプラクティスです。

パッケージが1つだけなら、サーバーのバージョンと完全に一致させます。パッケージが複数(npm版とNuGet版を同時提供する等)なら、サーバーのバージョンは全体のリリース番号として扱い、個々のパッケージのバージョンとは必ずしも一致させません。パッケージ種別ごとの識別子の違いを踏まえると、複数形式を並行提供するサーバーほど、この「サーバー版」と「パッケージ版」の使い分けが重要になります。

リモートサーバーの場合は、対応するAPIのバージョンとサーバーのversionを揃えるのが推奨です。https://api.myservice.com/mcp/v2.1のようなURLを使うサーバーなら、versionも2.1.0系にしておくと、利用者がAPIとサーバーの対応関係を読み取りやすくなります。リモートサーバーの公開手順で扱ったremotesプロパティと組み合わせて設計する項目です。

揃えを崩すとどうなるかも押さえておく価値があります。サーバーのversionだけを独自に進め、配下パッケージのversionを据え置いたままにすると、利用者は「MCP Registry上は3.0.0なのに、npmで見えるパッケージは1.2.0のまま」という状態に遭遇します。障害報告や質問のやり取りで、どちらの番号を指しているのか毎回確認し直す手間が発生し、サポート対応のコストに直結します。番号を揃えることは見た目の整合性以上に、問い合わせの精度を左右する実務上の判断です。

アグリゲーター側の並び替えロジックを知っておく

MCP Registryのメタデータを取り込むダウンストリームのアグリゲーター(マーケットプレイス等)には、バージョン比較の推奨ルールが示されています。優先順位は次の通りです。

  1. 「latest」フラグが付いているバージョンを常に新しいとみなす
  2. 両方がsemverとして解釈できるなら、semverの比較規則に従う
  3. どちらもsemverでなければ、公開されたタイムスタンプで比較する
  4. 一方だけsemverなら、semver側を新しいとみなす

この規則を読むと、非semver形式を選ぶこと自体は禁止されていませんが、複数のアグリゲーターをまたいだ挙動の予測しやすさでは明確にsemverが有利です。タイムスタンプ比較にフォールバックする経路は、アグリゲーターの実装次第でズレが出る余地を残しています。公開頻度が高いサーバーほど、素直にsemverへ寄せておくほうが運用上の驚きが少なくなります。

具体例で考えてみます。あるサーバーが1.0.0を公開したあと、日付ベースの2025.06.18という非semver文字列で次のバージョンを公開したとします。どちらもsemverとして読めそうに見えますが、2025.06.18は2025.6.18と書いた場合に限り厳密なsemverの3点構成として解釈され、ゼロ埋めした06表記では非semver扱いになります。表記のわずかな違いだけで、latest判定のロジックが変わってしまう典型例です。日付を使う場合は、ゼロ埋めするかどうかを最初に決め、公開のたびに揺らさないようにする必要があります。

混同しやすい別のバージョニング概念

「バージョニング」という言葉は、Claude関連のエコシステムだけでも複数の文脈で使われます。たとえばAnthropic APIのツール定義には、日付形式の名前でバージョンを表す独自の慣習があり、MCP Registryのサーバーバージョンとは設計思想も更新の単位もまったく別物です。両者を混同すると、片方のルールをもう片方に当てはめて誤った運用をしてしまいます。詳しくはClaude APIツールのバージョン管理で扱っています。

呼び名が同じでも、何を識別するための番号なのかは仕組みごとに違います。MCP Registryのversionはサーバーの1回の公開を指すラベルで、範囲や互換性の宣言ではありません。読み替えずに、仕組みごとの定義を都度確認する姿勢が実務では安全です。

まとめ

MCP Registryのバージョンは、公開ごとに一意で不変という前提のもとに設計されています。semverが強く推奨される一方、範囲指定の構文だけは明確に禁止され、それ以外の文字列は許容されます。メタデータだけを直したいときはプレリリース表記、複数パッケージやリモートAPIとの整合を取りたいときはサーバー版とパッケージ版の使い分け、という2つの実務パターンを覚えておけば、公開後に困る場面の大半はカバーできます。

番号の付け方に迷ったら、まずsemverに寄せ、既存パッケージのバージョンと揃えることを基準にすると判断しやすくなります。

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

関連する記事

MCP をもっと見る →