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.
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
