旧クライアントへの対応を維持しながら HTTP MCP サーバーを 2026-07-28 に移行する

目的

2026年10月25日時点の情報である。2025-11-25 クライアント向けに明示的にサポートする処理経路を維持しつつ、HTTP MCP サーバーをリビジョン 2026-07-28 に移行する。デプロイ前に、対象リビジョンのトランスポート仕様、メッセージスキーマ、採用する SDK が文書で示す対応状況を再確認する。これは受け入れ手順の提案であり、移行を実施して検証した結果の報告ではない。

前提条件

クライアントのプロトコルリビジョン、初期化ハンドラー、セッションストレージ、コールバック、サブスクリプション、認可ポリシーを洗い出す。本番と同様のゲートウェイの背後にステージング用エンドポイントを設け、ロールバック用設定と両リビジョンのクライアントを用意する。無害なテスト用ツールと、別々のテスト用 ID を使用する。実際の SDK パッケージバージョンを記録する。プロトコルリビジョンとパッケージバージョンは別のものである。

手順

1. プロトコルごとに処理経路を分離する。 互換性ルールでは、1つのエンドポイントで両方の動作を扱える。従来の initialize では従来の意味論を、新方式のリクエストごとのメタデータではステートレス処理を選択する。旧リビジョンのクライアントをサポートしている間は、そこでネゴシエーションした動作を維持する。新方式のヘッダー要件を従来の初期化に一律に適用してはならない。

2. リクエスト単体で処理を完結させる。 params._meta の io.modelcontextprotocol/protocolVersion と io.modelcontextprotocol/clientCapabilities を必須にする。推奨に従ってクライアントの識別情報も含めるが、この自己申告の情報を認可の根拠にしてはならない。機能やアプリケーションのコンテキストを以前の接続から取得する設計をやめる。複数の呼び出しにまたがる状態には、明示的な識別子を公開する。

3. ディスカバリーとトランスポートの検証を実装する。 server/discover を実装し、バージョンを MCP-Protocol-Version にも反映し、必須ヘッダーと本文の整合性を検証する。認証のないステージング用エンドポイントでディスカバリーを簡易確認する例を示す。

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   例示の URL を置き換える。保護されたエンドポイントでは、その環境で承認されている認証済みテストクライアントを使う。この確認のために認証を無効にしてはならない。

4. 結果と対話処理を更新する。 通常の結果には resultType: "complete" を出力する。許可された対話型操作には MRTR を実装する。input_required を返した後、新しいリクエスト ID で、対応する inputResponses と変更されていない不透明な requestState を受け付ける。状態が権限やビジネスロジックに影響する場合は、その完全性を検証し、推奨に従ってプリンシパル、有効期限、元の操作に結び付ける。必要な場合は、サーバー側で1回限りの使用を強制する。

5. 通知とキャッシュを移行する。 独立した GET 通知ストリームを subscriptions/listen に置き換える。リクエスト単位の SSE を利用している場合は維持するが、Last-Event-ID による再開は廃止する。応答ストリームを閉じることがキャンセルの合図になる。キャッシュ仕様の対象となる完了結果には、0以上の ttlMs と適切な cacheScope を追加する。中間結果と MRTR 再試行の結果はキャッシュしない。

6. バージョン不一致からの復旧を意図的にテストする。 未対応の新方式のバージョンには、対応バージョンを含む UnsupportedProtocolVersionError が返る。クライアントは互換性のあるバージョンで再試行するべきである。HTTP 400 の場合は JSON-RPC 本文を調べる。認識できる新方式のエラーなら修正またはバージョン選択が必要であり、本文が空か認識できない場合は従来の初期化へのフォールバックが認められる。有効な新方式のリクエストが拒否されたという理由だけでダウングレードしてはならない。

7. 実際のデプロイ経路を通して検証する。 ステージングで、ディスカバリー、一覧取得、無害な呼び出し、対話型の再試行、サブスクリプションをゲートウェイ経由で実行する。旧クライアントでも繰り返し、新方式のリクエストは複数のインスタンスに振り分ける。無害な SSE 応答を中断し、キャンセルと、ストリーム再開に依存しない安全な復旧を確認する。各 ID の認可を検証し、リクエストメタデータが変更されずにサーバーへ届くことを確認する。

期待される結果

サポートする両リビジョンで、それぞれのワークフローが完了する。新方式の操作はトランスポートセッションを必要とせず、旧クライアントはネゴシエーション済みのライフサイクルを維持する。受け入れ確認に合格するまで、旧設定を利用できる状態に保つ。

限界と検証の根拠

引用した仕様はプロトコルの動作を定義している。上記の手順は運用者が提案する検証計画である。SDK の互換性、業務操作の再試行の安全性、特定のロードバランサーでの正常動作を証明するものではない。それらにはデプロイ環境ごとのテストが必要である。