M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
M

MCP Handler

Community
Framework / SDK
Easily spin up an MCP server on Next.js, Nuxt, Svelte, and more

This is a framework for building MCP servers or agents, not a server you connect a client to.

How to install ↓ Compare GitHub source repository ↗
Category
Dev Tools #158 of 438
Stars
★ 692 Very popular
Transport
Streamable HTTP
Runtime
Node.js 20+
Credentials
No credential needed
Last commit
Tools
1
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.

Strongest · Documentation 13/20 Weakest · Reliability 9/20

Reliability
9/20
Security and permissions
11/20
Maintenance
12/20
Documentation
13/20
Setup experience
12/20
Why each score
Reliability 9/20
Only the README is available: no cached server manifest, no source files, no CI workflows and no committed tests, so the static review cannot verify the MCP init handshake, tool listing, or agreement between declared and actual behavior. The roll_dice example is internally coherent, and the README is explicit that createMcpHandler does not inspect the pathname and must be mounted by the host framework, which is a transparent, diagnosable design. However, the hard dependency on MCP SDK v2, zod ^4 and Node 20+, plus the 1.x/2.x branching, adds upgrade risk, and the claim of natively serving the 2026-07-28 spec with a stateless Streamable HTTP fallback is unsupported by any test or code. Per the static calibration rule, reliability cannot exceed 12 without verifiable execution evidence, so 9 is given: the happy path is plausible but edge cases and error handling are unproven.
Security and permissions 11/20
No malware, credential theft, covert exfiltration or unsafe default operations were found, so this does not fall into the 0-4 red-line band. Positive evidence: withMcpAuth verifies bearer tokens and returns RFC 9728-compliant WWW-Authenticate challenges, protectedResourceHandler only publishes protected resource metadata, and CIMD capability is correctly attributed to the authorization server rather than this package, showing least privilege and separation of concerns; dependency ranges are pinned. Deductions: the repository's license metadata is unknown while the README claims Apache-2.0, no source exists to audit token storage, log redaction or error-message leakage, the stdio client example implicitly fetches remote packages via npx, and there is no guidance that production deployments must use HTTPS/TLS.
Maintenance 12/20
With 669 stars, 36 open issues and not archived, this is an actively used project. The README documents the 1.x to 2.x migration path, removed items (redis, SSE transport, legacy route config) and dependency upgrade requirements, indicating versioning discipline. Deductions: the manifest reports License as unknown, contradicting the README's Apache-2.0 claim, so license evidence is missing; there is no commit history, release cadence, security-response channel or dependency-update policy; and responsiveness to the 36 open issues cannot be verified. Governance and license evidence gaps cap this at 12.
Documentation 13/20
Documentation is well layered: install commands, framework-compatibility matrix, a Next.js quick start, client connection options (both Streamable HTTP and mcp-remote), a protocol-generation support section, an authorization section, and links to three further docs (CLIENTS.md, AUTHORIZATION.md, ADVANCED.md). Limitations are disclosed explicitly: the pathname is not inspected, Express needs its own Web adapter, GET/DELETE session operations return 405, and Redis is no longer used. Deductions: the referenced doc files are not supplied with the source so their contents cannot be verified; highly forward-looking statements about the 2026-07-28 spec and CIMD lack reviewable evidence; and cost, rate limiting, troubleshooting and error-code listings are absent, leaving hidden assumptions.
Setup experience 12/20
The install path is clear: a single npm command installing three packages, with version constraints and a rollback note for 1.x users; the Quick Start provides a copy-pasteable route.ts and clarifies that /api/mcp is a convention rather than a requirement; client-side JSON config and the mcp-remote alternative are both given. Deductions: there is no verifiable execution evidence at all (no CI, no committed tests), so per the static calibration rule setup cannot exceed 15; real usability depends on whether the unreferenced mcp-handler@^2, @modelcontextprotocol/server@^2 and zod ^4 packages are actually published, and the Node 20+ and specific framework version requirements raise the bar further, making this a workable but unproven manual setup flow.

Static review · not runListed 2026-09-18

Read the FMRS scoring method →

Fit and risk

What it can accessUses the network

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

Setup

Before you start

Runtime：Node.js 20+

  1. Install dependencies: npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4.
  2. Create a route handler in your framework, e.g. app/api/mcp/route.ts in Next.js, calling createMcpHandler and registering tools.
  3. Export the handler: export { handler as GET, handler as POST }.
  4. Point clients at that route's complete URL (/api/mcp is a convention, not required).
  5. 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"
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

Generate and validate client config

Check that it works

Start the example Next.js app and check the client's tool list for roll_dice; sending a dice-rolling request should return text like "You rolled a X!", confirming the connection.

Troubleshooting

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

Things to try

Once connected, you can ask your AI assistant things like:

  • Roll a six-sided dice
  • Roll a 20-sided dice and tell me the result
  • Roll an 8-sided dice twice and give me both numbers
  • Roll a 100-sided dice once and show me the outcome

Tools 1

roll_dice read-only
Roll a dice with a specified number of sides.

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

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 64.1k · Tools 2 Compare with this →
Compare with other MCP servers

Source revision d7771d44adfb Data synced 2026-11-02 Read the FMRS scoring method