MCP TypeScript SDK v2入門｜v1からの変更点と最小サーバー

データコネクターと変換アダプター、精密工具を置いたMCP SDK移行のイメージ写真 MCP
カテゴリー
MCP
公開日
2026.09.06

はじめに

MCP（Model Context Protocol）のTypeScript SDK v2は、従来の単一パッケージからサーバー・クライアント別のパッケージへ移りました。検索で見つかるv1のコードをそのまま混ぜると、import先や起動方法が一致しません。

この記事では、ローカルのstdio接続で「2数を加算するツール」を公開します。MCPそのものの入門ではなく、v2へ移行する開発者が対象です。

先に用語を整理する

  • MCPサーバー：AIアプリから呼び出せるツールやデータを公開するプログラム
  • MCPクライアント：サーバーへ接続し、ツール一覧の取得や実行を行う側
  • stdio：ネットワークではなく、標準入力と標準出力で2つのプログラムを接続する方式
  • スキーマ：入力や出力に必要な項目とデータ型を定めたルール

この記事の完成物は画面を持つWebアプリではありません。クライアントからaddを呼び出すと、MCPサーバーが2つの数値を足して結果を返します。

主な変更点

項目v1系v2系
npmパッケージ@modelcontextprotocol/sdk@modelcontextprotocol/server、@modelcontextprotocol/clientなど
対象仕様2025年系2026-07-28
stdioの推奨入口サーバーとtransportを直接接続factoryを渡すserveStdio()も利用可能
スキーマraw Zod shapeの例が多いz.object()を明示する形が推奨

v2には旧世代を扱う互換機能もあります。ただし、新規コードでは同じ世代のパッケージ、仕様、サンプルをそろえる方が混乱しません。

必要環境

Node.jsのバージョンは、ターミナルでnode --versionを実行して確認します。続いて空のフォルダーで次を実行してください。

npm init -y
npm install @modelcontextprotocol/server@2.0.0 zod@4
npm install --save-dev typescript tsx

SDK v2のenginesはNode.js 20以上です。package.jsonには"type": "module"を設定し、起動用の"start": "tsx server.ts"をscriptsへ追加します。

最小サーバー

server.tsを作成します。

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

serveStdio(() => {
  const server = new McpServer({
    name: "kanimiso-calculator",
    version: "1.0.0",
  });

  server.registerTool(
    "add",
    {
      title: "加算",
      description: "2つの数値を加算します",
      inputSchema: z.object({
        a: z.number(),
        b: z.number(),
      }),
      outputSchema: z.object({ total: z.number() }),
    },
    async ({ a, b }) => {
      const output = { total: a + b };
      return {
        content: [{ type: "text", text: String(output.total) }],
        structuredContent: output,
      };
    },
  );

  return server;
});

保存後にnpm startを実行します。stdioサーバーはクライアントから入力を待つため、通常のWebサーバーのような画面は開きません。エラーを表示せず待機していれば、起動できている可能性があります。終了するときはCtrl+Cを押します。

contentは人や既存クライアントが読める表現、structuredContentはプログラムが扱いやすいオブジェクトです。outputSchemaを宣言した場合、返却値も一致させます。

動作確認

MCP Inspectorなど、stdio対応クライアントから起動コマンドを登録します。ツール一覧にaddが表示され、{ "a": 2, "b": 3 }で5が返れば正常です。

代表的な異常系も確認します。

  • bを省略：入力スキーマ検証で失敗する
  • aへ文字列を指定：数値ではないため失敗する
  • structuredContentのキーをresultへ変更：出力スキーマと不一致になる

移行手順

  1. 旧パッケージと新パッケージを同じファイルで混在させない
  2. importをserver/clientの役割ごとに変更する
  3. raw shapeをz.object()へ置き換える
  4. transport、HTTPアダプター、認証を公式移行ガイドで再確認する
  5. tools/list、正常なtools/call、不正入力をクライアントから試す

注意点

stdioでは標準出力がプロトコル通信に使われます。デバッグ文字列をconsole.log()で混ぜると通信を壊す可能性があるため、ログは標準エラーへ出します。また、ツールの入力検証は認可の代わりではありません。ファイル削除や外部送信を行うツールには、対象制限とユーザー確認を別途設けます。

よくあるトラブル

  • Cannot use import statement outside a module：package.jsonの"type": "module"を確認する
  • Cannot find package：記事と同じフォルダーでnpm installしたか確認する
  • クライアントにツールが出ない：起動コマンド、作業フォルダー、標準出力へ余計なログを出していないか確認する
  • v1の型エラーが残る：古いimportとv2のimportが同じファイルに混在していないか調べる

最初からHTTP公開や認証まで試すと原因を切り分けにくくなります。まずstdioで加算ツールを動かし、その後に接続方式を増やすのがおすすめです。

関連記事

まとめ

MCP TypeScript SDK v2移行の要点は、パッケージ分割、2026-07-28仕様、factoryベースの起動、明示的なスキーマです。まず小さなstdioサーバーで入出力を検証し、その後にHTTPや認証へ進むと切り分けやすくなります。

参考リンク

コメント

タイトルとURLをコピーしました