Skip to content
Back to search

mcp-handler

Easily spin up an MCP Server on Next.js, Nuxt, Svelte, and more

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vercel-labs/mcp-handler with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vercel-labs/mcp-handler'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vercel-labs--mcp-handler/badge.svg)](/listings/vercel-labs--mcp-handler)

HTML

<a href="/listings/vercel-labs--mcp-handler"><img src="/api/listings/vercel-labs--mcp-handler/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

> **Note**: `mcp-handler` 2.x requires the MCP SDK v2 packages (`@modelcontextprotocol/server` ^2.0.0), zod ^4.2.0, and Node.js 20+. If you're on `@modelcontextprotocol/sdk` 1.x, use `mcp-handler` 1.x.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 139 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcp-handler
  2. `mcp-handler` is a framework-agnostic HTTP adapter for hosting Model Context Protocol (MCP) servers in JavaScript and TypeScript applications. It turns an MCP server definition into a Web-standard `(Request) => Promise<Response>` handler that can be mounted in Next.js, Nuxt/Nitro, SvelteKit, Hono, and other Fetch-compatible frameworks.
  3. Built on MCP SDK v2, it serves the **2026-07-28** MCP specification natively while transparently falling back to stateless Streamable HTTP for 2025-era clients — one handler, both protocol generations.
  4. <p>
  5. <a href="https://vercel.com/labs#labs-products"><img alt="Vercel Labs Product" src="https://img.shields.io/badge/LABS-PRODUCT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a>
  6. <a href="https://www.npmjs.com/package/mcp-handler"><img alt="npm version: mcp-handler" src="https://img.shields.io/npm/v/mcp-handler.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
  7. <a href="https://www.npmjs.com/package/mcp-handler"><img alt="License: Apache-2.0" src="https://img.shields.io/npm/l/mcp-handler.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
  8. <a href="https://www.npmjs.com/package/mcp-handler"><img alt="npm downloads per month: mcp-handler" src="https://img.shields.io/npm/dm/mcp-handler.svg?style=for-the-badge&amp;labelColor=000000&amp;label=npm%20downloads" height="28"></a>
  9. </p>
  10. ## Installation
  11. ```bash
  12. npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4
  13. ```
  14. > **Note**: `mcp-handler` 2.x requires the MCP SDK v2 packages (`@modelcontextprotocol/server` ^2.0.0), zod ^4.2.0, and Node.js 20+. If you're on `@modelcontextprotocol/sdk` 1.x, use `mcp-handler` 1.x.
  15. ## Framework Compatibility
  16. `createMcpHandler` returns a Web-standard request handler, so the package is not tied to Vercel or any particular framework. It can be mounted in:
  17. - Next.js Route Handlers
  18. - Nuxt/Nitro server handlers using `fromWebHandler`
  19. - SvelteKit server routes
  20. - Hono routes using `c.req.raw`
  21. - Other frameworks that expose Fetch-compatible `Request` and `Response` APIs
  22. Frameworks based on Node.js `IncomingMessage` and `ServerResponse`, such as Express, require a Web Request adapter or the official MCP framework middleware.
  23. ## Quick Start (Next.js)
  24. ```typescript
  25. // app/api/mcp/route.ts
  26. import { createMcpHandler } from "mcp-handler";
  27. import { z } from "zod";
  28. const handler = createMcpHandler((server) => {
  29. server.registerTool(
  30. "roll_dice",
  31. {
  32. title: "Roll Dice",
  33. description: "Roll a dice with a specified number of sides.",
  34. inputSchema: z.object({
  35. sides: z.number().int().min(2),
  36. }),
  37. },
  38. async ({ sides }) => {
  39. const value = 1 + Math.floor(Math.random() * sides);
  40. return {
  41. content: [{ type: "text", text: `🎲 You rolled a ${value}!` }],
  42. };
  43. },
  44. );
  45. });
  46. export { handler as GET, handler as POST };
  47. ```
  48. `/api/mcp` is a convention, not a required path. `mcp-handler` does not inspect
  49. the request pathname, so you can place this handler at any framework route and
  50. give clients that route's complete URL.
  51. ## Connecting Clients
  52. If your client supports Streamable HTTP, connect directly:
  53. ```json
  54. {
  55. "remote-example": {
  56. "url": "http://localhost:3000/api/mcp"
  57. }
  58. }
  59. ```
  60. For stdio-only clients, use [mcp-remote](https://www.npmjs.com/package/mcp-remote):
  61. ```json
  62. {
  63. "remote-example": {
  64. "command": "npx",
  65. "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
  66. }
  67. }
  68. ```
  69. ## Protocol Support
  70. - **2026-07-28** (current): served natively — stateless, no sessions, per-request `_meta` envelope, `server/discover`.
  71. - **2025-era Streamable HTTP**: served via the SDK's stateless legacy fallback from the same handler. GET/DELETE session operations answer `405` (serving is stateless).
  72. - **HTTP+SSE transport (2024-11-05)**: removed in 2.x. Mount only the Streamable HTTP handler; unmounted `/sse` and `/message` paths are handled by your framework. Redis is no longer needed or used.
  73. ### Authorization (CIMD era)
  74. The 2026-07-28 spec deprecates Dynamic Client Registration (DCR) in favor of **Client ID Metadata Documents (CIMD)**, where the OAuth client identifies itself with an HTTPS URL that serves its metadata. CIMD support is advertised and implemented by your **authorization server** (`client_id_metadata_document_supported` in its RFC 8414 metadata); this package keeps your MCP server's resource-server surface up to date:
  75. - `withMcpAuth` verifies bearer tokens and answers `401`/`403` with RFC 9728-compliant `WWW-Authenticate` challenges pointing at your protected resource metadata.
  76. - `protectedResourceHandler` serves the RFC 9728 Protected Resource Metadata document listing your authorization servers.
  77. See [Authorization](docs/AUTHORIZATION.md) for wiring details.
  78. ## Migrating from 1.x
  79. - Install `@modelcontextprotocol/server` (v2) and `zod@^4`; remove `@modelcontextprotocol/sdk` and `redis`.
  80. - `inputSchema`/`argsSchema` take a full Standard Schema (e.g. `z.object({ ... })`) instead of a raw zod shape.
  81. - Variadic `server.tool(...)` / `.prompt(...)` / `.resource(...)` are removed — use `registerTool` / `registerPrompt` / `registerResource`.
  82. - In handler callbacks, `extra.authInfo` is now `ctx.http?.authInfo`.
  83. - `createMcpHandler(initialize, serverOptions, config)` is now `createMcpHandler(initialize, options)` — one options object combining the SDK's server options with `serverInfo`, `verboseLogs`, and `onEvent`.
  84. - Route and transport config options from 1.x (`basePath`, `streamableHttpEndpoint`, `sseEndpoint`, `sseMessageEndpoint`, `disableSse`, `redisUrl`, `maxDuration`, and `sessionIdGenerator`) are removed. Mount the handler at the desired route instead.
  85. ## Documentation
  86. - [Client Integration](docs/CLIENTS.md) - Claude Desktop, Cursor, Windsurf setup
  87. - [Authorization](docs/AUTHORIZATION.md) - OAuth and token verification
  88. - [Advanced Usage](docs/ADVANCED.md) - Dynamic routing, Nuxt, configuration options
  89. - [WebMCP Bridge](docs/WEBMCP.md) - Expose allowlisted tools to in-page agents (experimental)
  90. - [Observability](docs/OBSERVABILITY.md) - OpenTelemetry spans for Vercel's MCP observability
  91. - [MCP Events](docs/MCP_EVENTS.md) - Register draft webhook subscription methods with application-owned storage and delivery (experimental)
  92. ## Features
  93. - **Framework-agnostic**: Web-standard `Request` and `Response` handler
  94. - **Framework compatibility**: Next.js, Nuxt/Nitro, SvelteKit, Hono, and other Fetch-compatible frameworks
  95. - **Dual-era protocol support**: 2026-07-28 (stateless) and 2025-era Streamable HTTP from one handler
  96. - **Observability**: one OpenTelemetry span per MCP message, read by Vercel's MCP observability
  97. - **TypeScript Support**: Full type definitions included
  98. ## Requirements
  99. - Node.js 20+
  100. - A framework with Web-standard `Request` and `Response` APIs, either directly or through an adapter
  101. - Next.js 13+ when using Next.js, or Nuxt 3+ when using Nuxt
  102. ## License
  103. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.