powered by TechFeed
表示モード
Deep Dive

Claude CodeとCursorのMCPサーバー、バージョン固定の方法はドキュメントに書いていない——npxの`@バージョン`指定で代替するしかない現実

11月18日、Nirmataが「How to pin MCP server versions for Claude Code and Cursor」と題した記事を公開した。この記事では、Claude CodeとCursorでMCPサーバーのバージョンを固定する方法と、各ツールのドキュメントが実際にどこまでを定義しているかについて詳しく紹介されている。NirmataはKubernetes向けのセキュリティ・ポリシー管理製品を手がける企業で、CI/CDパイプラインにおけるソフトウェアサプライチェーンの完全性を重要視している。MCPサーバーをパイプライン内で管理・固定するというユースケースはNirmataの専門領域に直結しており、その観点からこの問題を整理した記事と言える。MCP(Model Context Protocol)とは、AIアシスタントが外部ツールやデータソースと連携するためのプロトコルで、Claude CodeやCursorのようなAIコーディングツールが外部サーバー経由で機能拡張できる仕組みだ。サーバーはnpmパッケージとして配布されることが多く、バージョン管理はパッケージ管...

11月18日、Nirmataが「How to pin MCP server versions for Claude Code and Cursor」と題した記事を公開した。この記事では、Claude CodeとCursorでMCPサーバーのバージョンを固定する方法と、各ツールのドキュメントが実際にどこまでを定義しているかについて詳しく紹介されている。

NirmataはKubernetes向けのセキュリティ・ポリシー管理製品を手がける企業で、CI/CDパイプラインにおけるソフトウェアサプライチェーンの完全性を重要視している。MCPサーバーをパイプライン内で管理・固定するというユースケースはNirmataの専門領域に直結しており、その観点からこの問題を整理した記事と言える。

MCP(Model Context Protocol)とは、AIアシスタントが外部ツールやデータソースと連携するためのプロトコルで、Claude CodeやCursorのようなAIコーディングツールが外部サーバー経由で機能拡張できる仕組みだ。サーバーはnpmパッケージとして配布されることが多く、バージョン管理はパッケージ管理の問題と重なる。

問題の核心は単純だ——MCPの公式ドキュメントにはバージョン固定の手段が一切記述されていない。セキュリティやCI環境の安定性を重視するエンジニアが「どのバージョンのサーバーを使っているか」を把握・管理しようとしても、ドキュメントはその問いに答えていない。これはエコシステムの成熟度の問題であり、現時点では開発者側が自衛的に対処するしかない。


結論から言う:MCPのドキュメントにバージョン固定の設定はない

Claude CodeのMCPドキュメントとCursorのMCPドキュメントのどちらにも、バージョンフィールド・バージョン範囲指定・ロックファイルに関する記述は一切存在しない。両ドキュメントの起動コマンド例はいずれも npx -y <パッケージ名> という形式で、バージョンは指定されていない。


バージョンを固定する唯一の方法:npxのパッケージ指定子を使う

ドキュメントにフィールドがない以上、npmの npx コマンド自体が持つ @バージョン 指定を使うのが現実的なアプローチだ。これはMCPの機能ではなく、npmの機能である。

Claude Codeでサーバーを追加する場合:

claude mcp add example --env API_KEY=your-key -- npx -y @example/[email protected]

プロジェクトの設定ファイル(.cursor/mcp.json または .mcp.json)に記述する場合:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@example/[email protected]"],
      "env": {
        "API_KEY": "${env:api-key}"
      }
    }
  }
}

重要な制限として、これはあくまで指定したパッケージ自体のバージョンを固定するだけであり、そのパッケージが依存する他のパッケージまでは固定されない。レビューした時点で何が動いていたかは、設定変更と同じコミットに記録しておくことが推奨されている。


認証情報はリテラル値で書くな

Claude CodeもCursorも、設定ファイル内で環境変数の展開をサポートしている。Cursorのドキュメントには「シークレットには環境変数を使うこと。ハードコードしてはならない」と明記されている。

Claude Codeでは ${VAR:-default} の形式でフォールバック値も設定できる。ただし「空文字列はセットされているとみなされる」ため、フォールバックが効かないケースがある点に注意が必要だ。

"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
  "Authorization": "Bearer ${API_KEY}"
}

両ツールのアップデート手順の違い

項目 Claude Code Cursor
プロジェクト設定ファイル .mcp.json .cursor/mcp.json
ユーザー設定 --scope user オプション ~/.cursor/mcp.json
バージョンフィールド なし なし
アップデート手順 記載なし 削除→キャッシュクリア→再追加

Cursorのアップデート手順は以下の3ステップだ:

  1. 設定画面からサーバーを削除する
  2. npm cache clean --force でキャッシュをクリアする
  3. サーバーを再追加する

Claude Codeは、接続中でもサーバーがツール一覧を変更して list_changed 通知を送れば、再接続なしに更新された一覧を取得できる。ただしこれはパッケージのバージョンアップとは別の話だ。


MCP_SDK_GENERATION はバージョン固定ではない

Claude Codeには MCP_SDK_GENERATION という環境変数があり、v1(MCP TypeScript SDK 1.x)または v2(SDK 2.0、プロトコルリビジョン2026-07-28対応)のクライアントランタイムを選択できる。しかしこれはクライアント側のランタイム選択であり、サーバーのパッケージバージョンを固定するものではない。Cursorに同等の設定はない。


レビューチェックリスト

記事では以下のチェックリストを提示している。各項目には、なぜそのチェックが必要かの背景も添えておく:

  1. プロジェクトファイルの起動コマンドが、レビューしたコマンドと(引数を含めて)一致しているか確認する。 ——バージョン指定はコマンド引数の中にしか存在しないため、引数レベルの一致確認が唯一の監査手段だ
  2. 認証情報がリテラル値でなく変数参照になっているか確認する。 ——設定ファイルはリポジトリにコミットされることが多く、シークレットの平文混入は即座にリスクになる
  3. 起動コマンドに正確なパッケージバージョン(例:@example/[email protected])が指定されており、その版数がサーバー追加時の変更に記録されているか確認する。 ——ロックファイル相当の仕組みがないため、コミット履歴がバージョン管理の代替となる
  4. アップデート後、Cursorでは削除・再追加を行い、/mcp ビューのツール一覧を承認済みのものと比較する。 ——キャッシュが残ったままでは新バージョンが反映されず、意図しない状態で稼働し続けるリスクがある
  5. Claude Codeでは list_changed 通知の後にツール一覧を再確認する。 ——通知を受けても実際のツール差分を目視確認しなければ、追加・削除されたツールを見落とす可能性がある

詳細はHow to pin MCP server versions for Claude Code and Cursorを参照していただきたい。