MCP Handler

Community

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

★ 669 Stars Category · Dev Tools Very popular

57FMRS · C

mcp-handler is a framework-agnostic HTTP adapter from Vercel that turns an MCP server definition into a Web-standard request handler mountable in Next.js, Nuxt/Nitro, SvelteKit, Hono, and other Fetch-compatible frameworks. Built on MCP SDK v2, it serves the 2026-07-28 spec natively with a stateless fallback for 2025-era clients, and includes withMcpAuth plus RFC 9728 protected resource metadata handling. It is Apache-2.0 licensed, requires Node.js 20+, and 2.x removes the HTTP+SSE transport and Redis dependency.

Reliability

9/20

Security and permissions

11/20

Maintenance

12/20

Documentation

13/20

Setup experience

12/20

Read the FMRS scoring method →

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. Note: this is a library for building MCP servers, not an MCP server itself.

Tools

roll_dice

Roll a dice with a specified number of sides.

Setup

Install dependencies: npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4.
Create a route handler in your framework, e.g. app/api/mcp/route.ts in Next.js, calling createMcpHandler and registering tools.
Export the handler: export { handler as GET, handler as POST }.
Point clients at that route's complete URL (/api/mcp is a convention, not required).
Clients supporting Streamable HTTP can connect directly; stdio-only clients can use mcp-remote.

claude_desktop_config.json

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

Generate and validate client config

Fit and risk

Best for

Developers working in JavaScript/TypeScript with Fetch-compatible frameworks
Teams wanting one handler that serves both new and legacy MCP clients
Stateless, per-request deployments that do not need Redis sessions
Projects needing RFC 9728 / RFC 8414 compliant authorization surfaces

Not for

Frameworks built on Node.js IncomingMessage/ServerResponse such as Express without a Web Request adapter
Projects still on @modelcontextprotocol/sdk 1.x (use mcp-handler 1.x instead)
Deployments requiring the HTTP+SSE (2024-11-05) transport, removed in 2.x
Environments running Node.js below 20

Required permissions

Access to the exposed HTTP route
Access to the authorization server that issues bearer tokens
Ability to configure protected resource metadata endpoints
Network access from the deployment to the authorization server when verifying tokens

Risks and side effects

Exposing the MCP handler publicly without auth can let arbitrary callers invoke registered tools
Tool return content flows into the model context, so sensitive data could leak
2.x is stateless, so GET/DELETE session operations return 405 and session-dependent clients may misbehave
Migrating from 1.x is a breaking change (full Standard Schema for inputSchema, removal of variadic methods, ctx.http?.authInfo), and improper upgrades cause runtime errors

Troubleshooting

Verify the MCP SDK v2 packages (@modelcontextprotocol/server ^2.0.0) are installed rather than @modelcontextprotocol/sdk 1.x
Check that Node.js 20 or newer is in use
Confirm the client URL points at the full path where the handler is actually mounted (not necessarily /api/mcp)
If the client is stdio-only, check that it is forwarded through mcp-remote
On 401/403, check withMcpAuth token verification and that the WWW-Authenticate challenge points at the correct protected resource metadata
For older clients that fail, confirm they are being served through the 2025-era stateless Streamable HTTP fallback

Use cases

Expose MCP tools inside a Next.js, Nuxt, SvelteKit, or Hono application

Serve an existing MCP server definition over stateless HTTP

Support both 2026-07-28 and 2025-era MCP clients from one handler

Implement OAuth bearer-token verification and protected resource metadata via withMcpAuth and protectedResourceHandler

Supported clients

Claude DesktopPartial support

CursorPartial support

WindsurfPartial support

Related MCP servers

Compare with other MCP servers