MCP TypeScript SDKをいま検索すると、最初に見るREADMEがすでにv2前提に寄っています。ただし、2026年6月18日時点では、v2はpre-alphaで、productionにはv1.xが推奨されています。ここを読み違えると、server作者は「新しいimport例をそのまま使うべきか」「既存のv1実装をすぐ直すべきか」で迷いやすくなります。
この記事は、2026年6月18日の巡回で確認した modelcontextprotocol/typescript-sdk のREADME、Releases、Issuesをもとにした実務メモです。結論から言うと、いきなり移行作業を始めるより、まず package.json、import、middleware、既知issueとの近さを読む小さな診断を挟むのが安全です。
v2を追う人と安定運用の人で読む場所が違う
現在のREADMEには、main branchがv2 SDKの開発中ブランチであること、安定版v2は2026年第3四半期に予定されていること、productionではv1.xが推奨されることが明記されています。さらに、v1 docsとv2 docsの入口も分かれています。
これは悪い状態というより、spec更新に合わせた移行期の自然な姿です。ただ、検索からREADMEに来た人は、ページのimport例やpackage名だけを見て「いまの推奨形」と誤解しやすいです。特に既存のMCP serverを保守している人は、v1のまま直すべき問題と、v2を試す時だけ見るべき問題を分ける必要があります。
- production運用: v1.x推奨を前提に、既存実装の安定性を優先する。
- 新spec追跡: v2 docs、split package、pre-alpha release、tracking issueを観察する。
- 移行準備: import、package、middleware、auth discoveryの差分をfixture化する。
split packageで迷う場所
v2では、従来の単一SDKを読む感覚から、@modelcontextprotocol/server、@modelcontextprotocol/client、さらにruntime/framework向けmiddleware packageへ分かれる方向が見えています。Releasesにも、2026年4月1日の @modelcontextprotocol/[email protected] と alpha.2、Node、Hono、Fastifyなどのalpha releaseが並んでいます。
ここで起きやすい失敗は、server本体の責任と、ExpressやHonoなどのweb framework側の責任を混ぜてしまうことです。たとえばHost header validation、JSON body parsing、Streamable HTTPのtransport wrapperは、MCPの機能そのものというより、runtimeに接続するための薄い層として読んだほうがよさそうです。
移行前に見たいもの: - package.json の @modelcontextprotocol/* dependency - import が v1 docs 由来か v2 docs 由来か - server/client package が混在していないか - middleware package に business logic を寄せていないか - framework側のbody parsingやheader validationを二重にしていないか
issueは「自分の実装ミス」と決めつけない
2026年6月上旬のissueには、v2-fixes、package export、OAuth discovery、timeout、invalid frameなど、実運用で見ると原因を切り分けにくい話題が並んでいます。たとえば SEP-2351 tracking issue では、RFC 8414のwell-known URI suffixに関する実装追跡が始まっています。
こういう時期に大切なのは、失敗をすぐ「自分のserver実装が悪い」と決めつけないことです。もちろん実装ミスの可能性はあります。ただ、SDK側の移行、package export、auth discovery、長時間requestのtimeoutが絡むと、同じ症状でも原因は複数あります。
- package export系: import pathと公開exportsのずれを見る。
- OAuth discovery系: well-known URI、issuer、resource metadataの前提を確認する。
- timeout系: tool実行時間、client側timeout、transport側timeoutを分ける。
- invalid frame系: server response、proxy、stream parsingのどこで壊れたかを分ける。
小さく作るならmigration doctor
この移行期に作るなら、いきなりserverへ接続する診断ツールより、read-onlyな mcp-sdk-migration-doctor くらいが扱いやすいです。対象は実行中のMCP serverではなく、まずはrepository内の package.json、import、config、最小fixtureです。
mcp-sdk-migration-doctor:
input:
- package.json
- TypeScript import snippets
- MCP server config fixture
- auth discovery fixture
checks:
- v1 SDK と v2 split package の混在
- main README由来のv2 importをproductionへ入れていないか
- middleware packageに責務を寄せすぎていないか
- package export issueに近いimport pathがないか
- OAuth discoveryのwell-known URI前提が古くないか
output:
- blocking
- migration
- observe
診断結果は、合格・不合格の二択にしないほうがよいです。v2はまだpre-alphaなので、今すぐ直すべきblocking、移行計画に入れるmigration、今週は観察でよいobserveに分けるほうが、個人開発や小さなagent環境には向いています。
記事としての実務メモ
MCP TypeScript SDK v2の移行期は、機能追加そのものよりも「どのドキュメントを読んでいるか」「どのpackageを参照しているか」「その失敗が既知issueに近いか」を先に分けるのが大事です。ここを曖昧にしたまま修正すると、v1 productionの安定性を落としたり、pre-alpha向けのimportを本番に混ぜたりしやすくなります。
まずはread-onlyに見る。package、import、middleware、auth discovery、timeoutだけを短いreportにする。MCP serverを動かす前のpreflightとして、このくらい小さな診断を挟むだけでも、SDK移行期の調査はかなり楽になります。
