Converts MCP server definitions into Web-standard request handlers for hosting Model Context Protocol servers in JavaScript and TypeScript applications.
Also known as vercel-labs/mcp-handler
- Stars
- 702
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- —
What is handler MCP?
handler converts MCP server definitions into Web-standard request handlers for hosting Model Context Protocol servers in JavaScript and TypeScript applications.
Summary generated from the project's README
About handler MCP server
Developers building JavaScript or TypeScript applications can use mcp-handler to transform MCP server definitions into standard Web request handlers. This allows you to host Model Context Protocol servers within modern web frameworks like Next.js, Nuxt/Nitro, SvelteKit, and Hono. By producing a standard (Request) => Promise<Response> function, the tool integrates directly into any environment that supports Fetch-compatible APIs.
The package provides native support for the 2026-07-28 MCP specification while maintaining compatibility with 2025-era clients through stateless Streamable HTTP. It requires Node.js 20 or higher, along with the MCP SDK v2 and Zod. For security, it includes utilities like withMcpAuth to verify bearer tokens and protectedResourceHandler to serve metadata compliant with RFC 9728.
Unlike older versions that required Redis or specific SSE endpoints, this version focuses on a stateless architecture. You can deploy it as a remote service for clients that support Streamable HTTP or use mcp-remote to connect stdio-only clients to your hosted endpoint.
What you can do with it
- 1Host MCP servers in web frameworksMount an MCP server directly into a Next.js Route Handler or a Hono route.
- 2Support multiple protocol generationsServe both the latest 2026-07-28 specification and legacy 2025-era clients using a single handler.
Written from the project's README. Every use case is checked against a quote from it.
How to install handler MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall handler MCP in Claude Code
$ claude mcp add mcp-handler -- npx -y mcp-handlerInstall handler MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-handler": {
"command": "npx",
"args": [
"-y",
"mcp-handler"
]
}
}
}Install handler MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-handler": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-handler"
]
}
}
}Install handler MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-handler","type":"stdio","command":"npx","args":["-y","mcp-handler"]}'Install handler MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-handler": {
"command": "npx",
"args": [
"-y",
"mcp-handler"
]
}
}
}Install handler MCP in Codex
$ codex mcp add mcp-handler -- npx -y mcp-handlerInstall handler MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-handler] command = "npx" args = ["-y", "mcp-handler"]
Install handler MCP in Gemini CLI
$ gemini mcp add -s user mcp-handler npx -- -y mcp-handlerInstall handler MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-handler": {
"command": "npx",
"args": [
"-y",
"mcp-handler"
]
}
}
}Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubmcp-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.
Installation
npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4
Note:
mcp-handler2.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/sdk1.x, usemcp-handler1.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
RequestandResponseAPIs
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)
// 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:
{
"remote-example": {
"url": "http://localhost:3000/api/mcp"
}
}
For stdio-only clients, use mcp-remote:
{
"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
_metaenvelope,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
/sseand/messagepaths 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:
withMcpAuthverifies bearer tokens and answers401/403with RFC 9728-compliantWWW-Authenticatechallenges pointing at your protected resource metadata.protectedResourceHandlerserves the RFC 9728 Protected Resource Metadata document listing your authorization servers.
See Authorization for wiring details.
Migrating from 1.x
- Install
@modelcontextprotocol/server(v2) andzod@^4; remove@modelcontextprotocol/sdkandredis. inputSchema/argsSchematake a full Standard Schema (e.g.z.object({ ... })) instead of a raw zod shape.- Variadic
server.tool(...)/.prompt(...)/.resource(...)are removed — useregisterTool/registerPrompt/registerResource. - In handler callbacks,
extra.authInfois nowctx.http?.authInfo. createMcpHandler(initialize, serverOptions, config)is nowcreateMcpHandler(initialize, options)— one options object combining the SDK's server options withserverInfo,verboseLogs, andonEvent.- Route and transport config options from 1.x (
basePath,streamableHttpEndpoint,sseEndpoint,sseMessageEndpoint,disableSse,redisUrl,maxDuration, andsessionIdGenerator) are removed. Mount the handler at the desired route instead.
Documentation
- Client Integration - Claude Desktop, Cursor, Windsurf setup
- Authorization - OAuth and token verification
- Advanced Usage - Dynamic routing, Nuxt, configuration options
- WebMCP Bridge - Expose allowlisted tools to in-page agents (experimental)
- MCP Events - Register draft webhook subscription methods with application-owned storage and delivery (experimental)
Features
- Framework-agnostic: Web-standard
RequestandResponsehandler - 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
- TypeScript Support: Full type definitions included
Requirements
- Node.js 20+
- A framework with Web-standard
RequestandResponseAPIs, either directly or through an adapter - Next.js 13+ when using Next.js, or Nuxt 3+ when using Nuxt
License
Apache-2.0
handler MCP questions
How do I add handler MCP to Claude Code?
Run claude mcp add mcp-handler -- npx -y mcp-handler in your terminal. Add --scope user to make it available in every project.
How do I add handler MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does it support the latest MCP specifications?
Yes, it natively serves the 2026-07-28 MCP specification while providing a fallback for 2025-era Streamable HTTP clients.