mcp-handler 是一个框架无关的 HTTP 适配器，用于托管 JavaScript 和 TypeScript 应用中的模型上下文协议（MCP）服务器。它将 MCP 服务器定义转化为 Web 标准的 (Request) => Promise 处理器，可挂载于 Next.js、Nuxt/Nitro、SvelteKit、Hono 及其他兼容 Fetch 的框架中。

它基于MCP SDK v2构建，原生支持2026-07-28 MCP规范，同时透明地退回到无状态的可流式HTTP，适用于2025时代的客户端——一个处理器，两代协议。

安装

注意：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 路由处理器
• 使用 fromWebHandler 的 Nuxt/Nitro 服务器处理器
• SvelteKit 服务器路由
• 使用[[T8]的Hono路线]
• 其他暴露兼容 Fetch 的 Request 和 Response API 的框架

基于Node的框架。

mcp-handler

mcp-handler is a framework-agnostic HTTP adapter for hosting Model Context Protocol (MCP) servers in JavaScript and TypeScript applications. It turns an MCP server definition into a Web-standard (Request) => Promise handler that can be mounted in Next.js, Nuxt/Nitro, SvelteKit, Hono, and other Fetch-compatible frameworks.

Built on MCP SDK v2, it serves the 2026-07-28 MCP specification natively while transparently falling back to stateless Streamable HTTP for 2025-era clients — one handler, both protocol generations.

Installation

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

Note: mcp-handler 2.x requires the MCP SDK v2 packages (@modelcontextprotocol/server ^2.0.0), zod ^4.2.0, and Node.js 20+. If you’re on @modelcontextprotocol/sdk 1.x, use mcp-handler 1.x.

Framework Compatibility

createMcpHandler returns a Web-standard request handler, so the package is not tied to Vercel or any particular framework. It can be mounted in:

• Next.js Route Handlers
• Nuxt/Nitro server handlers using fromWebHandler
• SvelteKit server routes
• Hono routes using c.req.raw
• Other frameworks that expose Fetch-compatible Request and Response APIs

Frameworks based on Node.js IncomingMessage and ServerResponse, such as Express, require a Web Request adapter or the official MCP framework middleware.

Quick Start (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 };