mcp-handler

# mcp-handler A Vercel adapter for the Model Context Protocol (MCP), enabling real-time communication between your applications and AI models. Currently supports Next.js and Nuxt with more framework adapters coming soon. ## Installation ```bash npm install mcp-handler @modelcontextprotocol/sdk zod@^3 # or yarn add mcp-handler @modelcontextprotocol/sdk zod@^3 # or pnpm add mcp-handler @modelcontextprotocol/sdk zod@^3 # or bun add mcp-handler @modelcontextprotocol/sdk zod@^3 ``` ## Next.js Usage ```typescript // app/api/[transport]/route.ts import { createMcpHandler } from "mcp-handler"; import { z } from "zod"; const handler = createMcpHandler( (server) => { server.tool( "roll_dice", "Rolls an N-sided die", { 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}!` }], }; } ); }, { // Optional server options }, { // Optional redis config redisUrl: process.env.REDIS_URL, basePath: "/api", // this needs to match where the [transport] is located. maxDuration: 60, verboseLogs: true, } ); export { handler as GET, handler as POST }; ``` ### Advanced Routing ```typescript // app/dynamic/[p]/[transport]/route.ts import { createMcpHandler } from "mcp-handler"; import type { NextRequest } from "next/server"; import { z } from "zod"; const handler = async ( req: NextRequest, { params }: { params: Promise<{ p: string; transport: string }> } ) => { const { p, transport } = await params; return createMcpHandler( (server) => { server.tool( "roll_dice", "Rolls an N-sided die", { 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}!` }], }; } ); }, { capabilities: { tools: { roll_dice: { description: "Roll a dice", }, }, }, }, { redisUrl: process.env.REDIS_URL, basePath: `/dynamic/${p}`, verboseLogs: true, maxDuration: 60, } )(req); }; export { handler as GET, handler as POST, handler as DELETE }; ``` ## Nuxt Usage ```typescript // server/api/mcp/[transport].ts import { createMcpHandler } from "mcp-handler"; import { getHeader, defineEventHandler, fromWebHandler } from "h3"; import { z } from "zod"; const handler = createMcpHandler((server) => { server.tool( "roll_dice", "Rolls an N-sided die", { 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}!` }] } } ) }, { // Optional server options }); export default fromWebHandler(handler); ``` ## Connecting to your MCP server via stdio Depending on the version of your client application, remote MCP's may need to use [mcp-remote](https://www.npmjs.com/package/mcp-remote) to proxy Streamable HTTP into stdio. If your client supports it, it's recommended to connect to the Streamable HTTP endpoint directly such as: ```typescript "remote-example": { "url": "http://localhost:3000/api/mcp", } ``` Due to client versions, and varying levels of support, you can list `mcp-remote` as the method for end users to connect to your MCP server. The above set up snippet will then look like: ```typescript "remote-example": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:3000/api/mcp" // this is your app/api/[transport]/route.ts ] } ``` ## Integrating into your client When you want to use it in your MCP client of choice: Depending on the version of your client application, remote MCP's may need to use [mcp-remote](https://www.npmjs.com/package/mcp-remote) to proxy Streamable HTTP into Stdio. ### Claude Desktop [Official Docs](https://modelcontextprotocol.io/quickstart/user) In order to add an MCP server to Claude Desktop you need to edit the configuration file located at: ```typescript "remote-example": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:3000/api/mcp" // this is your app/api/[transport]/route.ts ] } ``` macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json If it does not exist yet, you may need to enable it under Settings > Developer. Restart Claude Desktop to pick up the changes in the configuration file. Upon restarting, you should see a hammer icon in the bottom right corner of the input box. ### Cursor [Official Docs](https://docs.cursor.com/context/model-context-protocol) The configuration file is located at ~/.cursor/mcp.json. As of version 0.48.0, Curs