mcp-handler Documentation

To secure your MCP server, wrap your handler using the withMcpAuth function. This requires a verifyToken function that validates the incoming request and returns an AuthInfo object.

AuthInfo includes:

• token: The validated bearer token.
• scopes: An array of granted scopes.
• clientId: The unique identifier for the client.
• extra: An object for additional metadata.

Once wrapped, you can access the authenticated user's information within your tool handlers via ctx.http?.authInfo.

import { createMcpHandler, withMcpAuth } from "mcp-handler";
import type { AuthInfo } from "@modelcontextprotocol/server";

const handler = createMcpHandler((server) => {
  server.registerTool(
    "example",
    { /* ... schema ... */ },
    async (input, ctx) => {
      const authInfo = ctx.http?.authInfo;
      // Use authInfo.clientId or authInfo.token
      return { content: [{ type: "text", text: `Hello ${authInfo?.clientId}` }] };
    }
  );
}, {});

// Token verification function
const verifyToken = async (req: Request, bearerToken?: string): Promise<AuthInfo | undefined> => {
  // Implement your actual validation logic here
  if (!bearerToken) return undefined;
  return {
    token: bearerToken,
    scopes: ["read:stuff"],
    clientId: "user123",
    extra: { userId: "123" },
  };
};

// Wrap handler with authorization
const authHandler = withMcpAuth(handler, verifyToken, {
  required: true,
  requiredScopes: ["read:stuff"],
  resourceMetadataPath: "/.well-known/oauth-protected-resource",
});

export { authHandler as GET, authHandler as POST };

To support multi-tenant or dynamic MCP servers, you can use dynamic route segments (e.g., in Next.js [p]/mcp/route.ts) to capture tenant identifiers. Pass the request object to the function returned by createMcpHandler. This allows you to register tools or configure server behavior based on the dynamic parameters extracted from the URL.

// app/dynamic/[p]/mcp/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 }> },
) => {
  const { p } = await params;

  return createMcpHandler((server) => {
    server.registerTool(
      "roll_dice",
      {
        title: "Roll Dice",
        description: `Roll a dice for tenant ${p}.`,
        inputSchema: z.object({ sides: z.number().int().min(2) }),
      },
      async ({ sides }) => {
        const value = 1 + Math.floor(Math.random() * sides);
        return {
          content: [
            { type: "text", text: `🎲 Tenant ${p} rolled a ${value}!` },
          ],
        };
      },
    );
  })(req);
};

export { handler as GET, handler as POST };

When upgrading to 2.x, note the following breaking changes:

• Dependencies: Install @modelcontextprotocol/server (v2) and zod@^4. Remove @modelcontextprotocol/sdk and redis.
• Schema Definition: inputSchema/argsSchema now require a full Standard Schema (e.g., z.object({ ... })) instead of a raw zod shape.
• Registration Methods: Variadic methods like server.tool(), .prompt(), and .resource() are removed. Use server.registerTool(), server.registerPrompt(), and server.registerResource() instead.
• Context Access: In handler callbacks, extra.authInfo has changed to ctx.http?.authInfo.
• Handler Signature: createMcpHandler(initialize, serverOptions, config) is now createMcpHandler(initialize, options). The new options object combines SDK server options with serverInfo, verboseLogs, and onEvent.
• Configuration Removal: Route and transport config options (e.g., basePath, streamableHttpEndpoint, sseEndpoint, redisUrl, sessionIdGenerator) are removed. You must now mount the handler at the desired route within your framework.

You can host an MCP server in Next.js by using createMcpHandler within a Route Handler. The handler accepts an initialization function where you register tools, prompts, or resources using the MCP SDK v2.

Note that mcp-handler does not inspect the request pathname; you can mount the handler at any route (e.g., /api/mcp) and provide that full URL to your clients.

// app/api/mcp/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: z.object({
        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}!` }],
      };
    },
  );
});

export { handler as GET, handler as POST };