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) 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 Reusable Server Actions (Web UI + Tests) Server actions call the same logic as the MCP handler and power the web UI, keeping responses aligned. Lightweight MCP Route 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) 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.

mcp-server-skills