---
name: mcp-server-skills
description: Pattern for building MCP servers in Next.js with mcp-handler, shared Zod schemas, and reusable server actions.
---

## Links

- Model Context Protocol: https://modelcontextprotocol.io/
- mcp-handler (HTTP): https://www.npmjs.com/package/mcp-handler
- Reference implementation (Roll Dice): https://github.com/gocallum/rolldice-mcpserver
- Claude Desktop + mcp-remote bridge: https://www.npmjs.com/package/mcp-remote

## Folder Structure (Next.js App Router)

```
app/
  api/[transport]/route.ts   # One handler for all transports (e.g., /api/mcp)
  actions/mcp-actions.ts     # Server actions reusing the same logic/schemas
lib/
  dice.ts | tools.ts         # Zod schemas, tool definitions, pure logic
components/                  # UI that calls server actions for web testing
```

**Goal:** Keep `route.ts` minimal. Put logic + Zod schemas in `lib/*` so both the MCP handler and server actions share a single source of truth.

## Shared Zod Schema + Tool Definition

```ts
// lib/dice.ts
import { z } from "zod";

export const diceSchema = z.number().int().min(2);

export function rollDice(sides: number) {
  const validated = diceSchema.parse(sides);
  const value = 1 + Math.floor(Math.random() * validated);
  return { type: "text" as const, text: `🎲 You rolled a ${value}!` };
}

export const rollDiceTool = {
  name: "roll_dice",
  description: "Rolls an N-sided die",
  schema: { sides: diceSchema },
} as const;
```

## Reusable Server Actions (Web UI + Tests)

```ts
// app/actions/mcp-actions.ts
"use server";
import { rollDice as rollDiceCore, rollDiceTool } from "@/lib/dice";

export async function rollDice(sides: number) {
  try {
    const result = rollDiceCore(sides);
    return { success: true, result: { content: [result] } };
  } catch {
    return {
      success: false,
      error: { code: -32602, message: "Invalid parameters: sides must be >= 2" },
    };
  }
}

export async function listTools() {
  return {
    success: true,
    result: {
      tools: [
        {
          name: rollDiceTool.name,
          description: rollDiceTool.description,
          inputSchema: {
            type: "object",
            properties: { sides: { type: "number", minimum: 2 } },
            required: ["sides"],
          },
        },
      ],
    },
  };
}
```

Server actions call the same logic as the MCP handler and power the web UI, keeping responses aligned.

## Lightweight MCP Route

```ts
// app/api/[transport]/route.ts
import { createMcpHandler } from "mcp-handler";
import { rollDice, rollDiceTool } from "@/lib/dice";

const handler = createMcpHandler(
  (server) => {
    server.tool(
      rollDiceTool.name,
      rollDiceTool.description,
      rollDiceTool.schema,
      async ({ sides }) => ({ content: [rollDice(sides)] }),
    );
  },
  {}, // server options
  {
    basePath: "/api",     // must match folder path
    maxDuration: 60,
    verboseLogs: true,
  },
);

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

**Pattern highlights**
- Route only wires `createMcpHandler`; no business logic inline.
- `server.tool` consumes the shared tool schema/description and calls shared logic.
- `basePath` should align with the folder (e.g., `/api/[transport]`).
- Works for SSE/HTTP transports; stdio can be added separately if needed.

## Claude Desktop Config (mcp-remote)

```jsonc
{
  "mcpServers": {
    "rolldice": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
    }
  }
}
```

## Best Practices

1) **Single source of truth** — schemas + logic in `lib/*`; both MCP tools and server actions import them.  
2) **Validation first** — use Zod for inputs and reuse the same schema for UI + MCP.  
3) **Keep route.ts light** — only handler wiring, logging, and transport config.  
4) **Shared responses** — standardize `{ success, result | error }` shapes for tools and UI.  
5) **Vercel-friendly** — avoid stateful globals; configure `maxDuration` and `runtime` if needed.  
6) **Multiple transports** — expose `/api/[transport]` for HTTP/SSE; add stdio entrypoint when required.  
7) **Local testing** — hit server actions from the web UI to ensure MCP responses stay in sync.