@vercel/mcp-adapter

mcp-handler

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 规范，同时会透明地回退到无状态 Streamable HTTP，以兼容 2025 年的客户端——一个处理程序，支持两个协议世代。

安装

npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4

注意：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 返回一个符合 Web 标准的请求处理程序，因此此软件包不依赖 Vercel 或任何特定框架。它可以挂载到：

• Next.js Route Handlers
• 使用 fromWebHandler 的 Nuxt/Nitro 服务端处理程序
• SvelteKit 服务端路由
• 使用 c.req.raw 的 Hono 路由
• 其他提供兼容 Fetch 的 Request 和 Response API 的框架

基于 Node.js IncomingMessage 和 ServerResponse 的框架（例如 Express）需要使用 Web Request 适配器或官方 MCP 框架中间件。

快速开始（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 };

/api/mcp 是一种约定，并非必需的路径。mcp-handler 不会检查 请求路径名，因此你可以将此处理程序放在任何框架路由下，并将该路由的完整 URL 提供给客户端。

连接客户端

如果你的客户端支持 Streamable HTTP，可直接连接：

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

对于仅支持 stdio 的客户端，请使用 mcp-remote：

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

协议支持

• 2026-07-28（当前版本）：原生支持——无状态、无会话、每个请求都带有 _meta 信封、server/discover。
• 2025 年的 Streamable HTTP：由同一处理程序通过 SDK 的无状态旧版回退机制提供支持。GET/DELETE 会话操作会返回 405（服务为无状态）。
• HTTP+SSE 传输（2024-11-05）：已在 2.x 中移除。仅挂载 Streamable HTTP 处理程序；未挂载的 /sse 和 /message 路径由你的框架处理。不再需要或使用 Redis。

授权（CIMD 时代）

2026-07-28 规范弃用 Dynamic Client Registration（DCR），改用 Client ID Metadata Documents（CIMD）；在这种方式下，OAuth 客户端通过提供其元数据的 HTTPS URL 来表明自身身份。CIMD 支持由你的授权服务声明并实现（在其 RFC 8414 元数据中设置 client_id_metadata_document_supported）；此软件包则会确保你的 MCP 服务资源服务端接口保持最新：

• withMcpAuth 会验证 bearer token，并使用符合 RFC 9728 的 WWW-Authenticate 挑战响应 401/403，指向你的受保护资源元数据。
• protectedResourceHandler 会提供 RFC 9728 Protected Resource Metadata 文档，其中列出你的授权服务。

有关接线配置的详细信息，请参阅授权。

从 1.x 迁移

• 安装 @modelcontextprotocol/server（v2）和 zod@^4；移除 @modelcontextprotocol/sdk 和 redis。
• inputSchema/argsSchema 接受完整的 Standard Schema（例如 z.object({ ... })），而不是原始 zod 结构。
• 已移除可变参数形式的 server.tool(...) / .prompt(...) / .resource(...)，请改用 registerTool / registerPrompt / registerResource。
• 在处理程序回调中，extra.authInfo 现在是 ctx.http?.authInfo。
• createMcpHandler(initialize, serverOptions, config) 现在改为 createMcpHandler(initialize, options)——使用一个选项对象，合并 SDK 的服务选项与 serverInfo、verboseLogs 和 onEvent。
• 已移除 1.x 中的路由和传输配置选项（basePath、streamableHttpEndpoint、sseEndpoint、sseMessageEndpoint、disableSse、redisUrl、maxDuration 和 sessionIdGenerator）。请将处理程序挂载到所需路由。

文档

• 客户端集成 - Claude Desktop、Cursor、Windsurf 设置
• 授权 - OAuth 和令牌验证
• 高级用法 - 动态路由、Nuxt、配置选项
• WebMCP 桥接 - 向页面内 Agent 开放允许列表中的工具（实验性）
• MCP 事件 - 使用由应用程序管理的存储和交付，注册草案中的 webhook 订阅方法（实验性）

功能

• 与框架无关：符合 Web 标准的 Request 和 Response 处理程序
• 兼容多种框架：Next.js、Nuxt/Nitro、SvelteKit、Hono 及其他兼容 Fetch 的框架
• 双时代协议支持：通过单个处理程序支持 2026-07-28（无状态）和 2025 年版 Streamable HTTP
• TypeScript 支持：内含完整类型定义

要求

• Node.js 20+
• 支持 Web 标准 Request 和 Response API 的框架，可直接支持或通过适配器支持
• 使用 Next.js 时需 Next.js 13+，使用 Nuxt 时需 Nuxt 3+

许可证

Apache-2.0