mcp-handler는 JavaScript 및 TypeScript 애플리케이션에서 모델 컨텍스트 프로토콜(MCP) 서버를 호스팅하기 위한 프레임워크 무립 HTTP 어댑터입니다. MCP 서버 정의를 웹 표준 (Request) => Promise 핸들러로 변환하여 Next.js, Nuxt/Nitro, SvelteKit, Hono 및 기타 Fetch 호환 프레임워크에 마운트할 수 있습니다.

MCP SDK v2 기반으로 구축되었으며, 2026-07-28 MCP 사양을 네이티브로 제공하면서도 2025년 클라이언트에서는 상태 없는 Streamable HTTP로 투명하게 폴백됩니다 — 하나의 핸들러, 두 세대 프로토콜 모두.

설치

참고: 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는 웹 표준 요청 핸들러를 반환하므로, 패키지는 Vercel이나 특정 프레임워크에 묶이지 않습니다. 다음 프레임워크에 마운트할 수 있습니다:

• Next.js 루트 핸들러스
• [[T7]을 사용하는 Nuxt/Nitro 서버 핸들러]
• SvelteKit 서버 경로
• [[T8]를 사용하는 호노 노선
• 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 };