mcp-handler

A Vercel adapter for the Model Context Protocol (MCP), enabling real-time communication between your applications and AI models. Supports Next.js and Nuxt.

Installation

npm install mcp-handler @modelcontextprotocol/sdk@1.26.0 zod@^3

> Note: Versions of @modelcontextprotocol/sdk prior to 1.26.0 have a security vulnerability. Use version 1.26.0 or later.

Quick Start (Next.js)

// app/api/[transport]/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: {

          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}! }],

        };

      }

    );

  },

  {},

  {

    basePath: "/api", // must match where [transport] is located

    maxDuration: 60,

    verboseLogs: true,

  }

);
export { handler as GET, handler as POST };

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"]
  }
}

Documentation

- Client Integration - Claude Desktop, Cursor, Windsurf setup
- Authorization - OAuth and token verification
- Advanced Usage - Dynamic routing, Nuxt, configuration options

Features

- Framework Support: Next.js and Nuxt
- Multiple Transports: Streamable HTTP and Server-Sent Events (SSE)
- Redis Integration: Optional, for SSE transport resumability
- TypeScript Support: Full type definitions included

Requirements

- Next.js 13+ or Nuxt 3+
- Node.js 18+
- Redis (optional, for SSE)

License

Apache-2.0