Mcp Server Skills

This is a clean architecture pattern for building MCP servers in Next.js that keeps your route handlers thin and your logic reusable. The core idea is smart: define your tools once with Zod schemas in lib files, then share that exact code between your MCP endpoints and Next.js server actions. That means your web UI for testing and your actual MCP tools stay in sync automatically. It uses mcp-handler for HTTP transport, works with mcp-remote for Claude Desktop, and the folder structure is straightforward App Router stuff. If you're shipping MCP tools on Vercel or want a proper web interface alongside your AI integrations, this gives you a solid starting point without the usual duplication headaches.

skills.sh installs: 387
GitHub stars: 23
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills --agent claude-code

Installs into .claude/skills of the current project.

Files

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

// 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}!` };
}

SKILL.md on GitHub