公開2026.07.30更新2026.10.31 AIエージェント・MCP

MCP TypeScript SDK v2とは？パッケージ分割とステートレス化の移行要点【2.4.0対応】

MCP TypeScript SDKのv2は、単一の@modelcontextprotocol/sdkを畳み、@modelcontextprotocol/serverと@modelcontextprotocol/clientという別名のパッケージ群へ分かれました。npmのメタデータでは2.0.0が2026年7月27日23時55分（UTC）に公開され、10月31日時点の最新は10月23日公開の2.4.0です。この記事ではパッケージ構成と前提条件、2.4系までに入った変更点、2026-07-28仕様に対応するAPI、codemodによる移行手順、v1据え置きが妥当な条件を実装目線で整理します。MCP自体の仕組みはMCP（Model Context Protocol）の標準規格としての役割を先に押さえておくと読みやすくなります。

まとめ｜v2は別名パッケージへの移植であり、v1据え置きも成立する

v2はバージョン番号の更新ではなく、パッケージ名そのものが変わる移植です。v1の@modelcontextprotocol/sdkも保守が続いており、10月23日には1.32.2が出ました。npm上に非推奨の印は付いておらず、名前が違うため両者は同じpackage.jsonに共存できます。「v2が出たから上げる」ではなく、2026-07-28仕様を配信する必要があるかで決めます。

移行の価値があるのは、ステートレスなHTTP配信で水平に並べたい場合、Mcp-Methodヘッダでルーティングしたい場合、長時間ストリームなしでユーザー入力を挟むツールを作りたい場合の3つです。なお2026-07-28版のMCP Tasks拡張はSDKに実行時実装が無く、ハンドラの自前登録が要ります。逆にNode 18固定の基盤、SSEServerTransport依存のクライアント群、SDKをpeerDependencyで公開しているライブラリのいずれかなら、据え置きが合理的です。

すでにv2へ移った案件は、2.0.0のまま止めずに2.4系まで上げるかを個別に判断します。2.3.0でサーバーインスタンスの共有が拒否されるようになり、2.4.0では数値型の引数にx-mcp-headerを付けたツールが一覧から外れます。どちらもアップグレード注記に書かれた挙動変更なので、次の章で該当箇所を確かめてから上げてください。

v2のパッケージ分割とNode 20・zod 4という前提条件の整理

v1は依存を1パッケージへ抱え込む構成でしたが、v2はサーバー実装・クライアント実装・スキーマ定数・フレームワーク接続を切り出しました。

@modelcontextprotocol/sdkから分かれた5系統のパッケージ構成

v2の全パッケージは@modelcontextprotocolスコープ配下にあります。以下はスコープを省いた表記で、版は2.4.0リリースノートの対応表に基づきます。

パッケージ	担当範囲	10月31日時点
server	サーバー実装とHTTP入口	2.4.0
client	クライアントとOAuth	2.4.0
core	公開Zodスキーマ定数	2.4.0
core-internal	非公開・直接importしない	未公開
node	Node標準HTTPへの接続	2.1.2
express・hono	各フレームワークへの接続	2.0.2
fastify	Fastifyへの接続	2.0.1
server-legacy	凍結版SSEと認可サーバー	2.4.0
codemod	v1からの書き換えツール	2.4.0

アダプタ4種の実体は@modelcontextprotocol/node、同/express、同/hono、同/fastifyです。アダプタはserver本体と別に版が進み、2.4.0の時点でもexpressとhonoは2.0.2、fastifyは2.0.1のままでした。v2のアダプタはフレームワーク側をpeerDependencyとして宣言するため、express本体は自分でインストールします。2.4.0と同時に出たnodeの2.1.2は、@hono/node-serverの許容範囲を1.x系と2.x系の両方へ広げ、新規インストールで解決されるのは2.x系です。core-internalは非公開で、型やエラークラスはserverかclientから受け取ります。

Node 20以上・ESM優先とCommonJS併載という実行環境の条件

engines表記はnode >=20で、2.4.0でも変わっていません。v1は1.32.2でもnode >=18のままです。Node 18で固定された基盤はここで止まります。モジュール形式は二次情報に「ESM専用」と残っており、公式のチュートリアルにも同趣旨の一文がありますが、実際のパッケージメタは違いました。2.4.0のexportsにはimport条件とrequire条件の両方が入り、mainにはdist/index.cjsが指定されています。beta.1はimportだけでCommonJSから読めず、beta.5以降でmainに.cjsが現れました。効くのはテスト環境です。Jestのようにrequireで解決するランナーでも、moduleNameMapper回避を外せます。ただし2.1.0ではCommonJSのTypeScriptプロジェクトで型検査が通らなくなる退行があり、2.2.0で修正されています。CommonJSのまま使う場合の下限は2.2.0以降です。

2.0.0安定版が公開された時点とbeta系からの主な変更差分

npm registryのtimeフィールドでは、server・client・coreとも2.0.0が7月27日23時55分（UTC）に公開されています。日本時間なら7月28日の朝で、2026-07-28仕様の確定と同じタイミングです。系列はalpha.4が6月30日、そこからbeta.1からbeta.5を経て安定版へ至りました。移植に響く差分は、スキーマ定数の実体が@modelcontextprotocol/coreへ集約された点、serverInfoが応答の_metaへ移った点、ワイヤスキーマ構築が遅延化され事前構築にはpreloadSchemasが要る点の3つです。alphaでワイヤ専用メンバーを直接読んでいたコードは手直しが必要になります。

zod 4系への依存とzod 3固定環境で起きるバンドル増加

serverとclientはzod ^4.2.0に依存し、2.4.0でも同じ範囲です。v1はzod 3系と4系の両方を許す範囲だったため、zod 3をホイストしたワークスペースでも重複しませんでした。v2では重複排除が効かず、各パッケージが自分の下にzod 4のコピーを抱えます。公式ガイドは大規模なSPAでの実測として、zod 3のままclientとserverを追加するとJS全体がgzipで約83KB（全体比約0.7%）増えたという記載です。zodをパスの部分一致で拾うmanualChunksは、ネストしたコピーも先読みチャンクへ引き込みます。zod ^4.2.0へ上げれば重複が消えるため、移行と同時にzodを上げる順序が手戻りを減らします。

2.0.0から2.4.0までの更新内容と上げる前に読むアップグレード注記

2.0.0の公開から3か月で、マイナー版は2.4.0まで進みました。各リリースノートの冒頭にある「Upgrade notes」は、既存コードの挙動が変わる項目だけを集めた欄です。2.0.0で止まっている案件は、ここを順に読めば上げたときに壊れる箇所を洗い出せます。

版	公開日（UTC）	挙動が変わる主な項目
2.2.0	9月28日	M2M認証の発行者指定
2.3.0	10月2日	1リクエスト1サーバー
2.3.1	10月5日	legacy側の受信者検証
2.4.0	10月23日	数値型ヘッダ引数の拒否

2.2.0で変わったOAuth発行者の検証とlist系呼び出しの全件取得

2.2.0のリリースノートでは、マシン間認証用のClientCredentialsProviderやPrivateKeyJwtProviderをexpectedIssuerなしで生成すると、非推奨の警告がログへ出るようになりました。値には、資格情報を登録した認可サーバーのissuerを渡します。fetchToken()は送信前にクライアント情報の紐づく認可サーバーを照合し、食い違えばAuthorizationServerMismatchErrorを投げます。もう1つの変更はlist系です。cursorを渡さずに呼んだlistTools()などはnextCursorを最後まで辿り、全件を返します。1ページ目だけを前提にページングを自前で書いていたコードは、二重取得にならないか見直しが必要です。上限はlistMaxPagesで抑えられます。

2.3.0の1リクエスト1サーバー化と同一オリジン限定のリダイレクト

移行済みの案件で最も影響が大きいのは2.3.0です。接続中のインスタンスに対するServer.connect()は拒否され、ステートレスなStreamable HTTPのトランスポートは1リクエストだけを扱います。McpServerを1つ作って全リクエストで共有する書き方は動かなくなるため、リクエストハンドラの中かcreateMcpHandlerのファクトリの中でサーバーを作ります。リリースノートの説明では、生成のコストは小さく抑えられる設計です。HTTPクライアントのトランスポートは、スキーム・ホスト・ポートが同じオリジンへのリダイレクトだけを追うようになりました。別ホストへ転送するゲートウェイを挟む構成では、最終URLを直接設定するか、トランスポートにredirectPolicyを指定します。同じ版で、ツール引数の配列要素数とオブジェクトのメンバー数を抑えるmaxToolInputElementsと、自サーバー宛てに発行されたトークンだけを受けるexpectedResourceが加わりました。どちらも指定しない限り無効です。2.3.1では、server-legacyのrequireBearerAuthにも同じexpectedResourceが入りました。

2.4.0のSkills拡張とx-mcp-headerの数値型拒否という変更点

2.4.0はclient・server・core・server-legacy・codemodを2.4.0へ揃えた版です。アップグレード注記は3点あります。1つ目は、number型の引数にx-mcp-headerを付けたツールの扱いです。2026-07-28仕様の要求どおり、クライアントはそのツールを一覧に載せず、サーバーは呼び出しを-32020で返します。z.int()へ変えるか、注釈を外して対応します。2つ目は、z.object(...).meta({ id })から作ったoutputSchemaの結果です。2025-11-25の接続で{ result }に包まれなくなったため、structuredContent.resultではなくstructuredContentを読みます。3つ目は、同梱のAjvが使うfast-uriが3.1.8になった点です。my_tool:outputのように不正なURIスキームを持つ$idや$refはコンパイルできず、そのスキーマを持つツールは不正スキーマのエラーになります。

新機能の目玉はSkills over MCP（SEP-2640）です。サーバーはloadSkills(folder)でスキルのフォルダを読み込み、attach(server)で配信します。クライアントはSkillsClientで一覧・取得・検証を行い、サイズとダイジェスト、SKILL.mdのフロントマターが合わなければ発生するのはSkillVerificationErrorです。2025-11-25と2026-07-28の両方で動きますが、attachは実験扱いで、マイナー版で変わり得ると明記されています。本番で依存するなら版を固定してください。認可まわりでは、OAuthClientProviderにscopeForRefresh(tokens)を実装すると、トークン更新時にscopeを送れるようになりました。scopeのない更新を拒むMicrosoft Entra ID（AADSTS90009）への対処で、実装しなければ既定の送信内容は変わりません。v1→v2の移行ガイドがエージェント向けのスキルとしても配布されるようになったのも、この版からです。

2026-07-28仕様のステートレス設計とv2実装の対応関係

前提として、v2へ上げただけでは2026-07-28のバイトはワイヤに出ません。手で組んだClientやMcpServerは、書かれた通りの2025年系プロトコルを話し続けます。新仕様の配信は常に明示的なオプトインです。仕様本文はMCP仕様の2026-07-28版で、SDK側の対応方法は2026-07-28対応ガイドにまとまっています。仕様側の変更点を先に把握したい場合は、MCP仕様2026-07-28版のステートレス化と2025-11-25版からの移行手順で全体を整理しています。

initializeハンドシェイク廃止とdiscoverへの機能一覧取得の移行

2026-07-28仕様では初期化ハンドシェイクが消え、機能一覧はserver/discoverで取得します。リクエストが自己記述的なので、どのインスタンスが処理してもかまいません。入口はClientOptionsのversionNegotiationで、modeにautoを指定すると探りを入れ、2025年系のみのサーバーなら従来のハンドシェイクへ落ちます。決着した世代はgetProtocolEraで読めます。癖があるのは失敗時の扱いです。HTTPの401や403は世代の証拠として扱われず、typedな認可失敗としてconnectが拒否されます。stdioでは探り専用に使い捨ての兄弟プロセスを起動します。初期化前の未知リクエストで終了する実装への配慮です。

セッションIDに代わるrequestStateの署名付き受け渡し

2026-07-28仕様はリクエスト単位で、Mcp-Session-Idがありません。v1でセッションIDを鍵に状態を持っていたサーバーは、requestStateへ置き換えます。クライアントがそのまま送り返す不透明な文字列で、読み出しはctx.mcpReq.requestStateで行います。間違えやすいのは信頼境界で、クライアントを経由して戻る値は信頼できない入力です。createRequestStateCodecに鍵とTTLを渡すとmintとverifyの対が返り、mintはJSONをHMAC-SHA256で封印し、verifyはrequestState.verifyへ割り当てます。署名であって暗号化ではないため、秘密を詰めてはいけません。検証に失敗した再入は、ツールの手前で-32602として弾かれます。

サーバーからクライアントへの要求を畳み込むinputRequiredの往復

2026-07-28仕様では、サーバーからクライアントへ向かうJSON-RPC要求チャネルが撤去されました。ユーザーへの問いかけ（elicitation）やモデル呼び出し（sampling）は、tools/callのハンドラからinputRequiredを返し、クライアントが同じ呼び出しを応答付きで再送する形へ変わります。クライアント側は既定で自動充足し、登録済みのハンドラで応答を作り、requestStateの完全一致エコーを添えて再送します。上限はmaxRoundsの既定10ラウンドです。2025年系の接続には互換シムが実際のサーバー発要求へ変換するため、世代の分岐は要りません。

Mcp-Method系ヘッダとttlMs必須化というHTTP層の変更

ゲートウェイがJSON本文を解析せずに振り分けられるよう、Streamable HTTP上にMCP-Protocol-Version、Mcp-Method、Mcp-Nameの3つの標準ヘッダが加わりました。createMcpHandlerは新仕様の経路でこれらを本文と突き合わせ、不一致なら400とJSON-RPCの-32020（HeaderMismatch）で拒否します。x-mcp-headerを指定した引数はMcp-Param-{Name}ヘッダへ写されますが、資格情報付きCORSで動的な名前を許可一覧へ載せられないため、ブラウザのクライアントは写し込みを行いません。前述のとおり2.4.0からは、number型の引数へのx-mcp-header指定そのものが仕様違反として拒否されます。キャッシュ側ではttlMsとcacheScopeが必須化され、既定は0とprivateです。方針はcacheHintsで与えます。2.4.0で入ったSkills拡張の結果スキーマもこの規則に従い、2026-07-28の接続ではttlMsとcacheScopeが必須です。詳細はMCPの新トランスポートであるStreamable HTTPとSSEの違いを押さえておくと整理しやすくなります。

codemodによるv1からv2への移行手順と手作業が残る領域

名前が変わる移植なので、import文の書き換え量は多くなります。公式はts-morphベースのcodemodを用意しており、機械的に決まる対応は自動で当たります。全体の流れは公式の移行ガイド（Upgrading from v1.x to v2）が一次情報です。

codemod実行の正しい起点とpackage.jsonまで含む書き換え範囲

起点を間違えると効果が半分になります。公式ガイドはパッケージルート、つまりカレントディレクトリを対象に実行するよう指示しています。srcだけを渡すのは誤りです。package.jsonの依存関係も書き換え、testやscriptsからもSDKをimportしているためです。

Node 20以上を用意する（前提確認）
パッケージルートでcodemodのv1-to-v2を実行する
@mcp-codemod-errorをgrepし、自動化できなかった箇所を洗い出す
tsc –noEmit で型エラーを潰す
フォーマッタをかける（codemodは整形しない）
テストを実行する

当たる範囲はimportパスの付け替えに留まりません。McpErrorからProtocolErrorへの改名、setRequestHandlerの第1引数をメソッド文字列へ変える書き換え、extraからctxへの再割り当て、toolからregisterTool系への書き換えまで含みます。モノレポで書き換わるマニフェストは、上へ辿って最初の1つだけです。

インストールからcodemod実行、型検査までを通すコマンド例

上の手順をそのまま打てる形にしたのが次の例です。v1を残したままv2とzod 4を足し、パッケージルートでcodemodを流します。codemodの実行コマンドは移行ガイドの記載どおりで、2.4.0ではcodemod自体もserverと同じ版で公開されています。

# Node 20以上かを確認する
node --version

# v1は残したまま、v2本体とzod 4を追加する
npm install @modelcontextprotocol/server@^2.4.0 @modelcontextprotocol/client@^2.4.0 zod@^4.2.0

# パッケージルート（srcではない）を対象にcodemodを実行する
npx @modelcontextprotocol/codemod@latest v1-to-v2 .

# 自動化できなかった箇所を洗い出し、型検査を通す
grep -rn "@mcp-codemod-error" --exclude-dir=node_modules .
npx tsc --noEmit

HTTPで配信するサーバーは、2.3.0以降の規則に合わせてファクトリの中でMcpServerを組み立てます。次は公式ドキュメントのHTTP配信例に沿った最小構成で、Cloudflare WorkersやDeno、BunのようなWeb標準ランタイムならこのままエクスポートすれば動きます。

import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

// リクエストごとに新しいMcpServerを返す（2.3.0以降は共有インスタンスが拒否される）
const handler = createMcpHandler(() => {
  const server = new McpServer({ name: 'notes', version: '1.0.0' });
  server.registerTool(
    'add-note',
    { description: 'Save a note', inputSchema: z.object({ text: z.string() }) },
    async ({ text }) => ({ content: [{ type: 'text', text: `Saved: ${text}` }] })
  );
  return server;
});

export default handler;

Node上のExpressやFastify、node:httpへ載せる場合は、@modelcontextprotocol/nodeのtoNodeHandlerで包みます。node:httpで直接受けるときは、公式ドキュメントの指定は、同じパッケージのHost・Origin検証をハンドラの前に置く構成です。接続先のAIエージェント側の組み立ては、MCPサーバーの作り方とAIエージェントへの接続手順でPython版を例に扱っています。

@mcp-codemod-errorマーカーが残る手作業対応の代表例

安全に書き換えられなかった箇所には、@mcp-codemod-errorのコメントが差し込まれます。手作業が残る代表格は次の通りです。

ヘッダの読み出し。Headersへ改名されるが、ブラケット参照をget呼び出しへ直すのは手作業
OAuthのエラークラス統合。InvalidGrantErrorの判定をOAuthErrorとOAuthErrorCodeの組へ寄せる
名前空間import経由のスキーマ参照。@modelcontextprotocol/coreから手で再import
SDKの型を引数で受け取るだけでimportを持たないファイル。codemodは到達しない

タスク機能はSEP-2663で削除され、GetTaskRequestSchemaを渡していた登録は診断として残ります。v2は.mjsと.cjsをdist直下へ並べるため、distを正規表現で読む自作ツールも動かなくなる対象です。2.4.0へ一気に上げる場合は、前章の注記にあるサーバーインスタンスの共有とx-mcp-headerの型も、このマーカー洗い出しと同じ段階で確認しておくと手戻りが減ります。

SSEServerTransport廃止とStreamable HTTPへの寄せ方

SSEServerTransportは削除され、移行先はStreamable HTTPになりました。暫定の橋渡しとしてserver-legacyのsseサブパスに凍結版が置かれています。server-legacyは凍結扱いですが、2.3.1でrequireBearerAuthにexpectedResourceが足されたように、v1と揃えるための最小限の変更は入ります。WebSocketClientTransportも仕様外という理由で消えました。codemodはNodeStreamableHTTPServerTransportへ改名しますが、Cloudflare WorkersやDeno、BunのようなWeb標準ランタイムならWebStandardStreamableHTTPServerTransportを選びます。判断はハンドラの入出力で決まり、NodeのIncomingMessageを受け取るなら前者、Web標準のRequestを受けてResponseを返すなら後者です。

v1とv2を同時導入する段階移行の手順と越えてはいけない境界

大きめのコードベースでは一括置換を避けられます。パッケージ名が違うので同居できるためです。安全な順序は、v2とzodの引き上げを先に入れてv1を残し、ディレクトリ単位で書き換え、誰もv1をimportしなくなってから依存を外す流れです。逆順にすると、書き換え前のimportがすべてTS2307で解決不能になります。越えてはいけない境界も1つあります。v1とv2のモジュールはクラスも型も別物で、instanceof判定も名前的な型検査も両者を跨ぎません。分割はプロセス境界かトランスポート境界で行い、共有をワイヤ形式だけに限定してください。

Go・C#・Python各SDKとの実装差と言語選定時の判断材料

2026-07-28仕様に向けたベータは4つのTier 1 SDKで同時に出ました。7月末の時点では成熟度にばらつきがありましたが、10月31日時点では4言語とも正式版が出ています。

Go SDK・C# SDK・Python版との版番号と移行負荷の差

言語	パッケージ	10月31日時点
TypeScript	server・client	2.4.0
Python	mcp	2.3.0
Go	go-sdk	v1.8.0
C#	ModelContextProtocol	2.3.0

版番号は揃いましたが、移行の重さは揃っていません。新仕様のステートレス配信を今期のプロダクトへ入れるなら、移行ガイドとcodemodが揃っているTypeScriptが最も摩擦の少ない選択です。GoならMCP Go SDKの環境構築と事前準備で押さえたv1系の作法がそのまま続きます。メジャー番号が変わっていないため、パッケージ名の差し替えは起きません。.NET側はMCP C# SDKでサーバー・クライアントを作る手順と1.xからの移行で扱った2系が基準です。Python版はFastMCPでMCPサーバーを構築する手順のとおりパッケージ名がmcpのままで、変更の主体はimportパスとAPI形状です。Python版の具体的な書き換えはMCP Python SDK v2 移行手順にまとめています。フレームワーク側のFastMCP 4のsessionless対応と3系からの移行判断も別記事で整理しました。各SDKの新仕様への対応範囲は版ごとに異なるため、採用前にそれぞれのリリースノートで確認してください。TypeScript版だけは名前そのものが変わるため、依存ピンのlintやCIのチェックが文字列として@modelcontextprotocol/sdkを持っていると差し替え後に落ちます。

既存Node資産の有無で変わるTypeScript版採用の妥当性

実務的な分かれ目は、既存のNode資産をどれだけ持っているかです。ExpressやFastify、Honoで動くAPIがあるなら、v2のアダプタで既存アプリの1エンドポイントとしてMCPを載せられます。専用サーバーを別に立てる必要はありません。逆にNodeの運用実績がない組織が新仕様のためだけにTypeScriptを選ぶと、ESMとCommonJSの混在、zodのメジャー差、Node 20への引き上げを同時に抱えます。さらにv2は3か月でマイナー版が4つ進み、そのたびにアップグレード注記を読む運用が要ります。Nodeの運用体制がなくMCPサーバーの設計と実装を外へ出す前提なら、生成AI開発・AI受託開発のように運用まで委託できる体制と自社で持つ範囲を先に切り分けておくと見積りがぶれません。

v2へ今すぐ移行する条件と、v1に据え置くべき現場の判断基準の整理

v2の公開は済んでいますが、全案件が今上げるべきだとは考えません。

2026-07-28仕様を今すぐ配信する必要がある案件の条件

次の3つのどれかに当たるなら、移行を先送りする理由はありません。1つ目は、クライアントが新仕様を固定で要求してくる場合です。versionNegotiationでpin指定を受けると、2025年系のみのサーバーへの接続はEraNegotiationFailedで拒否され、フォールバックが働きません。2つ目は、サーバーレスやエッジで水平にスケールさせたい場合です。セッションIDが消えるため、セッションアフィニティ前提のルーティングを捨てられます。3つ目は、問いかけを挟むツールを長時間の接続保持なしで作りたい場合です。2.4.0で入ったSkills拡張を使いたい場合も、v1には同等の機能がないため移行の動機になります。逆にステートレス化もヘッダルーティングも使わず、stdioでローカル起動するツールを配るだけなら書き換えコストに見合いません。同じ2026-07-28版で正式化された拡張フレームワークの側は、MCP Appsによる対話型UI拡張の仕組みと採用判断で整理しています。

v1に据え置くほうが正解になる3つの条件と移行を見送る判断基準

次の3条件は、新仕様の機能要求がない限り据え置きを選びます。第1にNode 18で固定された実行基盤です。v2のenginesはnode >=20なので、ランタイムを上げられないなら選択肢に入りません。第2にSSEServerTransport前提のクライアント群を抱えている場合です。server-legacyで延命はできますが、Streamable HTTPへ寄せる工事の先送りで、v2の利得を相殺します。第3にSDKをpeerDependencyとして公開しているライブラリです。ピア宣言の差し替えは利用者にとって破壊的変更であり、semverのメジャー更新として出す必要があります。どれにも当たらないなら判断は「急がない」で、四半期の計画へ組み込みます。v1は1.32系でも修正が続いており、1.32.0ではv2と同じexpectedResourceがトークン検証に入りました。据え置きは放置ではなく、1.x系の最新へ追随し続ける前提で成り立ちます。2026年10月にはSDKの脆弱性7件が公表され、1.x系と2.x系の両方に修正版が出ています。据え置く場合も、MCP TypeScript SDKの脆弱性：7件の対象版と更新後に要る設定変更で手元の版が対象かを先に確かめてください。

移行で失敗する典型パターンとリリース前に必ず確認すべき項目の整理

公式ガイドが警告する失敗形は、どれも踏みやすいものです。

codemodをsrcだけに当て、上位のマニフェストが書き換わり段階移行が崩れる
ホストのv1 SDKを型解決している社内パッケージの接点にcodemodを当て、実行時に落とす
v1時代のダブルキャストを残したまま移行し、v2の型で検出できたエラーを抑制し続ける
McpServerをモジュールの最上位で1つだけ作り、2.3.0以降で2本目のリクエストから接続が拒否される

リリース前の確認は5点です。src配下の外まで含めた@modelcontextprotocol/sdkのgrep、tsc –noEmitの通過、moduleNameMapperの削除、バンドル予算でネストしたzodを除外できているか、そして2.4.0で拒否されるnumber型引数へのx-mcp-header指定や不正スキームの$idが残っていないかを見ます。導入判断そのものはMCPサーバーの役割と標準規格としての仕組みが整理に使えます。

よくある質問

移行判断でよく問われる論点を、npmのパッケージメタと公式ガイド、各版のリリースノートの記載に沿って整理します。

v1の@modelcontextprotocol/sdkはもう使えなくなりますか？

いいえ。1.x系は保守が続き、10月31日時点の最新は10月23日公開の1.32.2です。npm上に非推奨の印は付いていません。名前が別なので同じpackage.jsonに同時に置けます。ただしv1側とv2側のオブジェクトを行き来させると、instanceof判定が通らなくなります。

v2はCommonJSのプロジェクトでも使えますか？

使えます。2.4.0のexportsにはrequire条件があり、mainに.cjsが指定されています。beta.1はimport条件だけだったため、その時期の情報に基づく「ESM専用」という記述は現状と合いません。CommonJSのTypeScriptで型検査が通らない退行は2.1.0で起き、2.2.0で直っているので、2.2.0以降を使ってください。

Node 18のままでv2を動かせますか？

公式にはサポートされません。v2のenginesは2.4.0でもnode >=20で、公式ガイドもNode 20以上を前提に求めています。v1の1.32.2はnode >=18なので、ランタイムを上げられない基盤ではv1に留まる判断です。移行計画では、Nodeの引き上げを先行タスクに分けます。

v2に上げるだけで2026-07-28仕様を話すようになりますか？

なりません。手で組んだClientやMcpServerは、2025年系プロトコルを話し続けます。新仕様の配信はHTTPならcreateMcpHandler、stdioならserveStdio、クライアント側はversionNegotiationという明示的なオプトインが必要です。検証では、どちらへ落ちたかをgetProtocolEraで確認します。

2.0.0で移行を終えた案件は2.4.0へ上げるべきですか？

上げる前提で、注記の該当箇所を先に直します。2.3.0からはMcpServerの共有が拒否されるため、ファクトリの中で生成しているかの確認が必要です。2.4.0ではnumber型引数へのx-mcp-header指定、包まれなくなったoutputSchemaの結果、不正スキームの$idが影響します。10月に公表された脆弱性の修正も2.x系の新しい版に入っているため、2.0.0に留め置く理由は乏しくなっています。codemodを流すだけでは注記の項目は直らないので、grepと型検査、テストの順で確かめてから上げてください。