适合谁
- 使用 JavaScript/TypeScript 和 Fetch 兼容框架的开发者
- 希望一份处理程序同时服务新老 MCP 客户端的团队
- 需要无状态、按请求处理、不依赖 Redis 会话的部署场景
- 需要 RFC 9728 / RFC 8414 兼容授权表面配置的项目
M
57FMRS · C
mcp-handler 是 Vercel 维护的框架无关 MCP 服务器 HTTP 适配层，把服务器定义变成 Web 标准请求处理程序，可挂载于 Next.js、Nuxt/Nitro、SvelteKit、Hono 等。它基于 MCP SDK v2，原生支持 2026-07-28 规范并回退兼容 2025 年代客户端，附带 withMcpAuth 和 RFC 9728 受保护资源元数据处理能力。采用 Apache-2.0 许可证，要求 Node.js 20+，2.x 已移除 HTTP+SSE 与 Redis 依赖。
mcp-handler 是一个与框架无关的 HTTP 适配器，用于在 JavaScript 和 TypeScript 应用中托管 Model Context Protocol (MCP) 服务器。它把 MCP 服务器定义转换成一个符合 Web 标准的 (Request) => Promise<Response> 处理程序，可挂载到 Next.js、Nuxt/Nitro、SvelteKit、Hono 等兼容 Fetch 的框架中。它基于 MCP SDK v2，原生支持 2026-07-28 MCP 规范，同时对 2025 年代的客户端自动回退到无状态的 Streamable HTTP——同一个处理程序兼容两代协议。注意：它本身不是 MCP 服务器，而是一个用于构建 MCP 服务器的库。
工具能力
roll_dice
投掷指定面数的骰子。
安装接入
- 安装依赖：npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4。
- 在框架中创建路由处理程序，例如 Next.js 的 app/api/mcp/route.ts，调用 createMcpHandler 并注册工具。
- 导出处理程序：export { handler as GET, handler as POST }。
- 将客户端指向该路由的完整 URL（/api/mcp 只是约定，并非必须）。
- 支持 Streamable HTTP 的客户端可直接连接；仅支持 stdio 的客户端可借助 mcp-remote。
claude_desktop_config.json
{
"remote-example": {
"url": "http://localhost:3000/api/mcp"
}
}
选型与风险
不适合谁
- 使用 Express 等基于 Node.js IncomingMessage/ServerResponse 且未加 Web Request 适配器的框架
- 仍在使用 @modelcontextprotocol/sdk 1.x 的项目（应改用 mcp-handler 1.x）
- 需要 HTTP+SSE (2024-11-05) 传输的部署（2.x 已移除）
- Node.js 低于 20 的运行环境
所需权限
- 对外暴露的 HTTP 路由访问权限
- 在 Next.js 中通常是 .env（默认 VERCEL_OIDC_TOKEN）或平台级环境变量中的令牌凭证
- 仅当自行实现 OAuth 时，需要配置授权服务器与受保护资源元数据端点
风险与副作用
- 把 MCP 处理程序暴露在公网而未加鉴权，可能让任意调用者执行已注册的工具
- 工具回调中返回的内容会进入模型上下文，若包含敏感数据可能被外泄
- 2.x 为无状态模式，GET/DELETE 会话操作返回 405，依赖会话状态的客户端可能行为异常
- 从 1.x 迁移时 API 变化较大（inputSchema 需完整 Standard Schema、variadic 方法移除、extra.authInfo 改为 ctx.http?.authInfo），升级不当会导致运行时错误
常见排障
- 确认安装的是 MCP SDK v2（@modelcontextprotocol/server ^2.0.0）而非 @modelcontextprotocol/sdk 1.x
- 检查 Node.js 版本是否为 20 及以上
- 确认客户端 URL 指向处理程序实际挂载的完整路径（不一定是 /api/mcp）
- 若客户端仅支持 stdio，检查是否通过 mcp-remote 转发
- 出现 401/403 时，检查 withMcpAuth 的令牌校验与 WWW-Authenticate 挑战指向的受保护资源元数据是否正确
- 旧客户端连接异常时，确认其是否走 2025 年代 Streamable HTTP 无状态回退路径
使用场景
在 Next.js / Nuxt / SvelteKit / Hono 应用中暴露 MCP 工具
将已有 MCP 服务器定义以无状态 HTTP 方式对外提供服务
同时兼容 2026-07-28 与 2025 年代 MCP 协议的客户端
通过 withMcpAuth 与 protectedResourceHandler 实现 OAuth 令牌校验和受保护资源元数据
支持客户端
Claude Desktop部分支持
Cursor部分支持
Windsurf部分支持