@vercel/mcp-adapter

mcp-handler

mcp-handler は、JavaScript および TypeScript アプリケーションで Model Context Protocol（MCP）サーバーをホストするための、フレームワークに依存しない HTTP アダプターです。MCP サーバー定義を Web 標準の (Request) => Promise<Response> ハンドラーに変換し、Next.js、Nuxt/Nitro、SvelteKit、Hono、その他の Fetch 互換フレームワークにマウントできます。

MCP SDK v2 を基盤とし、2026-07-28 MCP 仕様にネイティブで対応しながら、2025 年代のクライアントにはステートレスな Streamable HTTP に透過的にフォールバックします。1 つのハンドラーで、両世代のプロトコルに対応します。

インストール

npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4

注: mcp-handler 2.x には MCP SDK v2 パッケージ（@modelcontextprotocol/server ^2.0.0）、zod ^4.2.0、Node.js 20 以降が必要です。@modelcontextprotocol/sdk 1.x をお使いの場合は、mcp-handler 1.x を使用してください。

フレームワークの互換性

createMcpHandler は Web 標準のリクエストハンドラーを返すため、このパッケージは Vercel や特定のフレームワークに依存しません。以下にマウントできます。

• Next.js の Route Handlers
• fromWebHandler を使った Nuxt/Nitro のサーバーハンドラー
• SvelteKit のサーバールート
• c.req.raw を使った Hono のルート
• Fetch 互換の Request および Response API を公開するその他のフレームワーク

Express など、Node.js の IncomingMessage と ServerResponse を基盤とするフレームワークでは、Web Request アダプターまたは公式 MCP フレームワークミドルウェアが必要です。

クイックスタート（Next.js）

// app/api/mcp/route.ts
import { createMcpHandler } from "mcp-handler";
import { z } from "zod";

const handler = createMcpHandler((server) => {
  server.registerTool(
    "roll_dice",
    {
      title: "Roll Dice",
      description: "Roll a dice with a specified number of sides.",
      inputSchema: z.object({
        sides: z.number().int().min(2),
      }),
    },
    async ({ sides }) => {
      const value = 1 + Math.floor(Math.random() * sides);
      return {
        content: [{ type: "text", text: `🎲 You rolled a ${value}!` }],
      };
    },
  );
});

export { handler as GET, handler as POST };

/api/mcp は慣例的なパスであり、必須ではありません。mcp-handler はリクエストのパス名を検査しないため、このハンドラーは任意のフレームワークルートに配置でき、そのルートの完全な URL をクライアントに渡せます。

クライアントの接続

クライアントが Streamable HTTP に対応している場合は、直接接続します。

{
  "remote-example": {
    "url": "http://localhost:3000/api/mcp"
  }
}

stdio のみをサポートするクライアントには、mcp-remote を使用します。

{
  "remote-example": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
  }
}

プロトコルのサポート

• 2026-07-28（現行）：ネイティブで対応。ステートレスでセッションはなく、リクエストごとの _meta エンベロープと server/discover を使用します。
• 2025 年代の Streamable HTTP：同じハンドラーから SDK のステートレスなレガシーフォールバック経由で対応します。GET/DELETE によるセッション操作には 405 を返します（ステートレスで提供されます）。
• HTTP+SSE トランスポート（2024-11-05）：2.x で削除されました。Streamable HTTP ハンドラーのみをマウントしてください。マウントされていない /sse および /message パスは、フレームワークが処理します。Redis は不要になり、使用もされません。

認可（CIMD 時代）

2026-07-28 仕様では、Dynamic Client Registration（DCR）に代わり Client ID Metadata Documents（CIMD） が採用されています。CIMD では、OAuth クライアントはメタデータを提供する HTTPS URL によって自身を識別します。CIMD のサポートは、認可サーバーが自身の RFC 8414 メタデータで client_id_metadata_document_supported を指定して通知し、実装します。このパッケージは、MCP サーバーのリソースサーバーとしてのインターフェイスを最新の状態に保ちます。

• withMcpAuth はベアラートークンを検証し、RFC 9728 に準拠した WWW-Authenticate チャレンジとともに 401/403 を返し、保護対象リソースのメタデータを示します。
• protectedResourceHandler は、認可サーバーを列挙した RFC 9728 Protected Resource Metadata ドキュメントを提供します。

設定方法については、認可を参照してください。

1.x からの移行

• @modelcontextprotocol/server（v2）と zod@^4 をインストールし、@modelcontextprotocol/sdk と redis を削除します。
• inputSchema／argsSchema には、生の zod shape ではなく、完全な Standard Schema（例：z.object({ ... })）を指定します。
• 可変引数の server.tool(...)／.prompt(...)／.resource(...) は削除されました。registerTool／registerPrompt／registerResource を使用してください。
• ハンドラーコールバック内の extra.authInfo は、ctx.http?.authInfo に変更されました。
• createMcpHandler(initialize, serverOptions, config) は createMcpHandler(initialize, options) に変更されました。SDK のサーバーオプションに serverInfo、verboseLogs、onEvent を組み合わせた、1 つの options オブジェクトを指定します。
• 1.x のルートおよびトランスポート設定オプション（basePath、streamableHttpEndpoint、sseEndpoint、sseMessageEndpoint、disableSse、redisUrl、maxDuration、sessionIdGenerator）は削除されました。ハンドラーは任意のルートにマウントしてください。

ドキュメント

• クライアント連携 - Claude Desktop、Cursor、Windsurf のセットアップ
• 認可 - OAuth とトークン検証
• 高度な使い方 - 動的ルーティング、Nuxt、設定オプション
• WebMCP Bridge - ページ内エージェントに許可リスト登録済みツールを公開します（実験的）
• MCP Events - アプリケーション側のストレージと配信を使用して、ドラフト版の Webhook サブスクリプションメソッドを登録します（実験的）

機能

• フレームワーク非依存：Web 標準の Request および Response ハンドラー
• フレームワークとの互換性：Next.js、Nuxt／Nitro、SvelteKit、Hono、およびその他の Fetch 互換フレームワーク
• 2 世代のプロトコルをサポート：1 つのハンドラーで 2026-07-28（ステートレス）と 2025 年代の Streamable HTTP に対応
• TypeScript のサポート：完全な型定義が含まれています

要件

• Node.js 20 以降
• Web 標準の Request および Response API を直接、またはアダプター経由で使用するフレームワーク
• Next.js を使用する場合は Next.js 13 以降、Nuxt を使用する場合は Nuxt 3 以降

ライセンス

Apache-2.0