mcp-handler Skill 技能

技能简介

mcp-handler 是由 Vercel Labs 出品的框架无关的 MCP 服务器托管适配器。它能把一个 MCP 服务器定义，转换成一个符合 Web 标准的 (Request) => Promise 请求处理器，从而可以轻松挂载到 Next.js、Nuxt/Nitro、SvelteKit、Hono 以及其他兼容 Fetch 的框架中。

它基于 MCP SDK v2 构建，原生支持 2026-07-28 版 MCP 规范，同时能透明回退到面向 2025 时代客户端的无状态 Streamable HTTP，也就是说一个 handler 即可同时服务两代协议。npm 月下载量高达 357 万次，是 Vercel 官方在 MCP 托管方向的重要基础设施。

核心能力

• 框架无关：返回标准 Web 请求处理器，不绑定 Vercel 或任何特定框架，可自由挂载到多种运行时。
• 多框架兼容：支持 Next.js Route Handlers、Nuxt/Nitro（fromWebHandler）、SvelteKit 服务器路由、Hono（c.req.raw）等 Fetch 兼容框架。
• 双协议世代支持：基于 MCP SDK v2 原生提供 2026-07-28 规范服务，并自动回退到 2025 时代的无状态 Streamable HTTP。
• 简洁的工具注册：通过 createMcpHandler 传入回调，用 server.registerTool 配合 zod 定义输入 schema，快速注册工具。
• 类型安全：使用 TypeScript 与 zod v4 定义工具输入，类型与校验一并完成。
• 官方长期维护：由 Vercel Labs 维护，与 AI SDK、MCP 生态保持同步演进。

安装配置

1. 安装依赖：运行 npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4。
2. 版本要求：mcp-handler 2.x 需要 MCP SDK v2（@modelcontextprotocol/server ^2.0.0）、zod ^4.2.0 与 Node.js 20+；若仍在 SDK 1.x，请使用 mcp-handler 1.x。
3. 导入使用：在项目代码中 import { createMcpHandler } from "mcp-handler" 并配合 zod 定义工具。
4. Express 等框架：基于 Node.js IncomingMessage/ServerResponse 的框架（如 Express）需额外的 Web Request 适配器或官方 MCP 中间件。

使用步骤

1. 在项目中安装 mcp-handler 及所需的 MCP SDK v2、zod 依赖。
2. 在 Next.js 中创建路由文件，例如 app/api/mcp/route.ts。
3. 调用 createMcpHandler 并传入回调，在回调中用 server.registerTool 注册你的工具，并用 zod 描述输入 schema。
4. 导出由 createMcpHandler 返回的 handler，MCP 客户端即可通过该路由访问你的服务器。
5. 若使用 Nuxt/Nitro、SvelteKit 或 Hono，按框架对应方式（如 fromWebHandler、c.req.raw）挂载同一 handler。

适用场景

• 在 Web 应用中内嵌 MCP 服务：为已有的 Next.js / Nuxt 站点快速开放 MCP 接口，供 AI 客户端调用。
• Serverless 部署 MCP：借助 Web 标准 Request/Response 模型，把 MCP 服务器部署到 Serverless / 边缘运行时。
• 多框架复用同一套工具：团队内有多种前端框架时，用同一套 handler 代码统一接入。
• 兼容新旧客户端：需要同时服务支持新规范与旧规范的 MCP 客户端，避免为不同世代重复开发。

适用人群

在 JavaScript / TypeScript 生态中开发 Web 应用并希望为其增添 MCP 能力的全栈开发者，以及需要在 Serverless、边缘计算环境部署 MCP 服务器的工程团队。

工作原理

mcp-handler 把 MCP 服务器的定义包装成一个 Web 标准的 Fetch 请求处理器：客户端发来的 HTTP 请求在其中被解析为 MCP 消息并路由到对应工具，工具执行结果再被序列化为 HTTP 响应返回。它对内基于 MCP SDK v2，可原生讲 2026-07-28 版规范；当遇到只支持旧协议的客户端时，则自动切换为无状态 Streamable HTTP，从而用单一入口覆盖两代协议。

官方链接

• GitHub：https://github.com/vercel/mcp-handler
• npm：https://www.npmjs.com/package/mcp-handler