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.
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
Markdown
[](/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
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.
- # mcp-handler
- `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.
- 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.
- <p>
- <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&logo=Vercel&labelColor=000000" height="28"></a>
- <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&labelColor=000000" height="28"></a>
- <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&labelColor=000000" height="28"></a>
- <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&labelColor=000000&label=npm%20downloads" height="28"></a>
- </p>
- ## Installation
- ```bash
- 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.
- ## Framework Compatibility
- `createMcpHandler` returns a Web-standard request handler, so the package is not tied to Vercel or any particular framework. It can be mounted in:
- - Next.js Route Handlers
- - Nuxt/Nitro server handlers using `fromWebHandler`
- - SvelteKit server routes
- - Hono routes using `c.req.raw`
- - Other frameworks that expose Fetch-compatible `Request` and `Response` APIs
- Frameworks based on Node.js `IncomingMessage` and `ServerResponse`, such as Express, require a Web Request adapter or the official MCP framework middleware.
- ## Quick Start (Next.js)
- ```typescript
- // 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` is a convention, not a required path. `mcp-handler` does not inspect
- the request pathname, so you can place this handler at any framework route and
- give clients that route's complete URL.
- ## Connecting Clients
- If your client supports Streamable HTTP, connect directly:
- ```json
- {
- "remote-example": {
- "url": "http://localhost:3000/api/mcp"
- }
- }
- ```
- For stdio-only clients, use [mcp-remote](https://www.npmjs.com/package/mcp-remote):
- ```json
- {
- "remote-example": {
- "command": "npx",
- "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
- }
- }
- ```
- ## Protocol Support
- - **2026-07-28** (current): served natively — stateless, no sessions, per-request `_meta` envelope, `server/discover`.
- - **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).
- - **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.
- ### Authorization (CIMD era)
- 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:
- - `withMcpAuth` verifies bearer tokens and answers `401`/`403` with RFC 9728-compliant `WWW-Authenticate` challenges pointing at your protected resource metadata.
- - `protectedResourceHandler` serves the RFC 9728 Protected Resource Metadata document listing your authorization servers.
- See [Authorization](docs/AUTHORIZATION.md) for wiring details.
- ## Migrating from 1.x
- - Install `@modelcontextprotocol/server` (v2) and `zod@^4`; remove `@modelcontextprotocol/sdk` and `redis`.
- - `inputSchema`/`argsSchema` take a full Standard Schema (e.g. `z.object({ ... })`) instead of a raw zod shape.
- - Variadic `server.tool(...)` / `.prompt(...)` / `.resource(...)` are removed — use `registerTool` / `registerPrompt` / `registerResource`.
- - In handler callbacks, `extra.authInfo` is now `ctx.http?.authInfo`.
- - `createMcpHandler(initialize, serverOptions, config)` is now `createMcpHandler(initialize, options)` — one options object combining the SDK's server options with `serverInfo`, `verboseLogs`, and `onEvent`.
- - 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.
- ## Documentation
- - [Client Integration](docs/CLIENTS.md) - Claude Desktop, Cursor, Windsurf setup
- - [Authorization](docs/AUTHORIZATION.md) - OAuth and token verification
- - [Advanced Usage](docs/ADVANCED.md) - Dynamic routing, Nuxt, configuration options
- - [WebMCP Bridge](docs/WEBMCP.md) - Expose allowlisted tools to in-page agents (experimental)
- - [Observability](docs/OBSERVABILITY.md) - OpenTelemetry spans for Vercel's MCP observability
- - [MCP Events](docs/MCP_EVENTS.md) - Register draft webhook subscription methods with application-owned storage and delivery (experimental)
- ## Features
- - **Framework-agnostic**: Web-standard `Request` and `Response` handler
- - **Framework compatibility**: Next.js, Nuxt/Nitro, SvelteKit, Hono, and other Fetch-compatible frameworks
- - **Dual-era protocol support**: 2026-07-28 (stateless) and 2025-era Streamable HTTP from one handler
- - **Observability**: one OpenTelemetry span per MCP message, read by Vercel's MCP observability
- - **TypeScript Support**: Full type definitions included
- ## Requirements
- - Node.js 20+
- - A framework with Web-standard `Request` and `Response` APIs, either directly or through an adapter
- - Next.js 13+ when using Next.js, or Nuxt 3+ when using Nuxt
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.