mcp-handler

用于模型上下文协议 (MCP) 的 Vercel 适配器，可在您的应用程序与 AI 模型之间实现实时通信。支持 Next.js 和 Nuxt。

安装

npm install mcp-handler @modelcontextprotocol/sdk@1.26.0 zod@^3

注意：@modelcontextprotocol/sdk 版本低于 1.26.0 存在安全漏洞。请使用 1.26.0 或更高版本。

快速入门（Next.js）

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

const handler = createMcpHandler(
  (server) => {
    server.registerTool(
      "roll_dice",
      {
        title: "掷骰子",
        description: "掷一个指定面数的骰子。",
        inputSchema: {
          sides: z.number().int().min(2),
        },
      },
      async ({ sides }) => {
        const value = 1 + Math.floor(Math.random() * sides);
        return {
          content: [{ type: "text", text: `🎲 你掷出了 ${value}！` }],
        };
      }
    );
  },
  {},
  {
    basePath: "/api", // 必须与 [transport] 所在路径一致
    maxDuration: 60,
    verboseLogs: true,
  }
);

export { handler as GET, handler as POST };

连接客户端

如果您的客户端支持可流式传输的 HTTP，请直接连接：

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

对于仅支持标准输入输出的客户端，请使用 mcp-remote：

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

文档

• 客户端集成 - Claude Desktop、Cursor、Windsurf 的设置
• 授权 - OAuth 和令牌验证
• 高级用法 - 动态路由、Nuxt、配置选项

特性

• 框架支持：Next.js 和 Nuxt
• 多种传输方式：可流式传输的 HTTP 和服务器发送事件 (SSE)
• Redis 集成：可选，用于 SSE 传输的断点续传
• TypeScript 支持：包含完整的类型定义

要求

• Next.js 13+ 或 Nuxt 3+
• Node.js 18+
• Redis（可选，用于 SSE）

许可证

Apache-2.0

mcp-handler 快速上手指南

mcp-handler 是一个专为 Vercel 平台设计的 Model Context Protocol (MCP) 适配器，支持 Next.js 和 Nuxt 框架，可实现应用程序与 AI 模型之间的实时通信。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 运行时: Node.js 18 或更高版本
• 框架: Next.js 13+ 或 Nuxt 3+
• 可选依赖: Redis（仅在使用 SSE 传输且需要恢复连接时需要）

安装步骤

使用 npm 安装核心库及必要的依赖项。请注意，@modelcontextprotocol/sdk 必须使用 1.26.0 或更高版本以修复安全漏洞。

npm install mcp-handler @modelcontextprotocol/sdk@1.26.0 zod@^3

提示：国内开发者若遇到下载缓慢问题，可配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

基本使用 (Next.js)

以下示例展示如何在 Next.js App Router 中创建一个简单的 MCP 服务端点，注册一个“掷骰子”工具。

1. 在项目中的 app/api/[transport]/route.ts 路径下创建文件（[transport] 为动态路由段）。
2. 填入以下代码：

// app/api/[transport]/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: {
          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}!` }],
        };
      }
    );
  },
  {},
  {
    basePath: "/api", // 必须与 [transport] 所在的路径前缀匹配
    maxDuration: 60,
    verboseLogs: true,
  }
);

export { handler as GET, handler as POST };

3. 启动开发服务器，您的 MCP 服务即可在 http://localhost:3000/api/mcp (或其他 transport 名称) 访问。

客户端连接示例： 若您的客户端支持 Streamable HTTP，可直接配置 URL：

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