mcp-handler

mcp-handler turns an MCP server definition into a Web-standard (Request) => Promise<Response> handler, letting teams host Model Context Protocol servers inside their existing Next.js, Nuxt/Nitro, SvelteKit, or Hono applications instead of standing up a separate service. Built on MCP SDK v2, it serves the 2026-07-28 specification natively while falling back to stateless Streamable HTTP for 2025-era clients from the same handler.

Beyond the core adapter, the package ships an OAuth-aware auth wrapper (withMcpAuth) for RFC 9728 protected-resource metadata and bearer-token verification, plus a CLI (create-mcp-route) that scaffolds a ready-to-use MCP route in a Next.js project. Maintained by Vercel, it removes the boilerplate of wiring transport, protocol negotiation, and authorization when exposing tools, prompts, and resources to MCP clients.

What You Get

• A createMcpHandler factory that wraps @modelcontextprotocol/server’s McpServer into a Web-standard fetch handler mountable at any route
• Dual-era protocol support - serves the 2026-07-28 MCP spec natively and falls back to stateless Streamable HTTP for 2025-era clients from one handler
• withMcpAuth middleware for bearer-token verification, scope checks, and RFC 9728-compliant 401/403 challenge responses
• protectedResourceHandler and generateProtectedResourceMetadata helpers for serving OAuth Protected Resource Metadata
• A create-mcp-route CLI that scaffolds a working app/api/mcp/route.ts in an existing Next.js project and installs the required dependencies

Common Use Cases

• Exposing internal tools, prompts, and resources to Claude Desktop, Cursor, or Windsurf via a Next.js API route
• Adding an authenticated MCP endpoint to an existing product without deploying a separate server or session store
• Migrating an MCP server built on SDK v1 / HTTP+SSE transport to the current stateless Streamable HTTP spec
• Building a framework-agnostic MCP integration that needs to run on Nuxt, SvelteKit, or Hono instead of Next.js

Under The Hood

Architecture The package is a thin, focused adapter organized into three layers: the handler module wraps the MCP SDK’s createMcpHandler/McpServer into a per-request fetch handler, constructing a fresh server instance per request via a factory to avoid shared state across requests; the auth module separates OAuth concerns (a bearer-auth middleware and RFC 9728 metadata endpoints) from the protocol-serving concern; and the CLI is an entirely separate scaffolding tool with no coupling to the runtime handler. The design is straightforward middleware composition - the auth wrapper takes a plain Request-to-Response handler, attaches verified auth info, then delegates - and the handler itself proxies to the SDK’s own fetch method, meaning core protocol behavior is fully delegated rather than reimplemented, so the adapter layer is the only place that needs to change if the underlying SDK’s contract shifts.

Tech Stack TypeScript with a dual ESM/CJS build targeting Node 20+, built on the MCP server SDK as a peer dependency plus a schema-validation library for tool input schemas, with a minimal CLI dependency set and a test runner for its suite. Releases and versioning are managed through an automated changeset workflow with provenance-enabled publishing driven by CI. The package intentionally carries almost no runtime dependencies of its own, keeping the installed footprint small for consumers who add it alongside their chosen framework.

Code Quality The test suite includes an end-to-end style test that spins up a real HTTP server and exercises the handler through an actual MCP client - listing tools, prompts, and resources, calling tools, exercising auth failure paths, and pinning protocol versions - which is meaningfully thorough rather than shallow unit stubs. Error handling is deliberate rather than swallowed: authentication failures are translated into typed error objects mapped to proper HTTP status and challenge responses, and edge cases like malformed JSON bodies are explicitly commented as intentionally deferred to the SDK layer. Typing is strict and consistent across the public options and event surfaces; no dedicated linter configuration was found in the repository, and CI coverage is oriented around release automation rather than a visible lint/test-on-PR gate.

API Design The public surface is small and idiomatic for its target framework: a single factory call returns a handler that can be exported directly as route handlers, matching common app-router conventions with minimal ceremony, and the auth wrapper composes as ordinary middleware around that handler. Defaults are sensible - subscription limits, stateless legacy fallback, and auto-detected origin for resource metadata - so a working server needs only a tool registration and no transport configuration. The scaffolding CLI further lowers the barrier by generating a working example and installing dependencies in one command; this isn’t a novel technical breakthrough, but collapsing SDK migration pain and dual-protocol serving into a drop-in import is a genuine, specific developer-experience advantage over hand-wiring the underlying SDK.