← 返回目录

MCP Handler

社区

框架 / SDK

在 Next.js、Nuxt、Svelte 等框架中轻松搭建 MCP 服务器

这是用于开发 MCP Server 或 Agent 的框架，不是可以直接连接到客户端的 Server。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 158 / 438
Stars: ★ 692 非常热门
传输方式: Streamable HTTP
运行环境: Node.js 20+
凭据: 无需凭据
最近提交: 4 天前
工具数: 1

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 依赖。

最强项 · 文档质量 13/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

11/20

维护活跃度

12/20

文档质量

13/20

安装易用性

12/20

查看各项评分依据

可靠性 9/20: 仅提供 README，未缓存 server manifest，也未提供任何源码文件、CI 工作流或提交的测试，静态评审无法验证 MCP 初始化握手、工具列表与声明行为是否一致。README 中的 roll_dice 示例逻辑自洽，且明确说明 createMcpHandler 不检查路径、需自行挂载，属于可诊断的透明设计；但依赖要求（MCP SDK v2、zod ^4、Node 20+）与 1.x/2.x 双版本分支带来升级风险，文档宣称原生服务 2026-07-28 规范并回退到无状态 Streamable HTTP，却无任何测试或代码佐证。据静态校准规则，缺少可验证执行证据，可靠性不得高于 12，故取 9：happy path 可信但边界与错误路径证据缺失。
安全与权限 11/20: 未发现恶意代码、凭据窃取、隐蔽外传或默认危险操作等红线行为，因此不落入 0-4 区间。正面证据：withMcpAuth 校验 bearer token 并返回符合 RFC 9728 的 WWW-Authenticate 挑战，protectedResourceHandler 只暴露受保护资源元数据，CIMD 相关能力被明确归属到授权服务器而非本包，体现最小权限与职责分离；依赖版本被显式锁定范围。扣分点：仓库未缓存 license 元数据（README 称 Apache-2.0 但 manifest 为 unknown），无任何源码可供审计 token 存储、日志脱敏或错误信息泄露路径，示例中 stdio 客户端通过 npx 拉取远程包属于隐式外部网络依赖，且未说明生产环境必须 TLS/HTTPS。
维护活跃度 12/20: stars 669、开放 issue 36、未归档，属于有实际使用者的活跃项目，README 详述了 1.x 到 2.x 的迁移路径、移除项（redis、SSE 传输、旧路由配置）与依赖升级要求，说明存在版本化维护意识。扣分点：manifest 显示 License 为 unknown，与 README 声明的 Apache-2.0 不一致，许可证证据缺失；未提供任何提交记录、发布时间表、安全响应渠道或依赖更新策略；36 个开放 issue 的响应情况无从核实。治理与许可证证据缺口使其停在 12。
文档质量 13/20: 文档分层清晰：安装命令、框架兼容矩阵、Next.js 快速开始、客户端连接（Streamable HTTP 与 mcp-remote 两种配置）、协议支持代际说明、授权章节，并指向 docs/CLIENTS.md、AUTHORIZATION.md、ADVANCED.md 三份延伸文档。明确披露了限制：不检查路径名、Express 需自行适配、GET/DELETE 会话操作返回 405、Redis 不再使用。扣分点：目标文档文件未随源码提供，无法核验内容真实性；2026-07-28 与 CIMD 这类高度前瞻的表述缺乏可复查依据；未涉及成本、限流、故障排查与错误码列表，存在隐藏假设。
安装易用性 12/20: 安装路径清晰：一条 npm 命令安装三个包，附带版本约束说明与 1.x 用户回退指引；Quick Start 给出可直接复制的 route.ts，并说明 /api/mcp 只是约定而非强制；客户端侧同时提供 JSON 配置与 mcp-remote 方案。扣分点：全程无任何可验证执行证据（无 CI、无提交测试），按静态校准 setup 不得高于 15；且真实可用性取决于未提供的 mcp-handler@^2、@modelcontextprotocol/server@^2 与 zod ^4 是否已发布，Node 20+ 与特定框架版本要求进一步抬高门槛，属于可能可行但未经证实的手动配置流程。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络

适合谁

使用 JavaScript/TypeScript 和 Fetch 兼容框架的开发者
希望一份处理程序同时服务新老 MCP 客户端的团队
需要无状态、按请求处理、不依赖 Redis 会话的部署场景
需要 RFC 9728 / RFC 8414 兼容授权表面配置的项目

不适合谁

使用 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），升级不当会导致运行时错误

安装接入

准备工作

运行环境：Node.js 20+

安装依赖：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"
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

生成并校验客户端配置

验证是否装好

启动示例 Next.js 应用后，在客户端工具列表中应出现 roll_dice 工具；发送一个掷骰子的请求，返回类似“你掷出了 X”的文本即说明连接成功。

常见排障

确认安装的是 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 无状态回退路径

试试这样问

连接成功后，可以直接对 AI 助手这样说：

掷一个六面的骰子
帮我掷一个20面的骰子，告诉我结果
掷两次8面骰子并把点数告诉我
用100面的骰子掷一次看看是多少

工具能力 1

roll_dice 只读

投掷指定面数的骰子。

使用场景

在 Next.js / Nuxt / SvelteKit / Hono 应用中暴露 MCP 工具

将已有 MCP 服务器定义以无状态 HTTP 方式对外提供服务

同时兼容 2026-07-28 与 2025 年代 MCP 协议的客户端

通过 withMcpAuth 与 protectedResourceHandler 实现 OAuth 令牌校验和受保护资源元数据

支持客户端

Claude Desktop部分支持

Cursor部分支持

Windsurf部分支持

依据项目文档列出，未经本站实测。

详细介绍

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 服务器的库。