mcp-server-skills_skill

Overview

This skill provides a pattern for building Model Context Protocol (MCP) servers in Next.js using mcp-handler, shared Zod schemas, and reusable server actions. It shows how to keep route handlers minimal while sharing validation and business logic between MCP endpoints and Next.js server actions. The setup is designed for Next.js App Router, Prisma-ready backends, and compatibility with AI SDKs and local testing tools.

How this skill works

Place validation and pure logic in a shared lib/ folder (Zod schemas, tool definitions, and functions). Wire a minimal app/api/[transport]/route.ts that uses createMcpHandler to register tools with their schemas and call the shared logic. Implement server actions (app/actions/*.ts) that call the same shared functions so the web UI and tests use identical behavior and response shapes.

When to use it

• Building an MCP-compatible API that must match web UI behavior
• When you want a single source of truth for input validation and tool metadata
• Deploying to serverless platforms (Vercel) where route code should stay lightweight
• Testing and iterating locally with server actions and mcp-remote bridges
• Exposing multiple transports (HTTP, SSE, stdio) from the same codebase

Best practices

• Keep Zod schemas and pure functions in lib/ so both MCP and server actions import them
• Make route.ts only responsible for handler wiring, transport config, and logging
• Reuse the same input schemas for UI forms and tool definitions to avoid drift
• Return standardized shapes like { success, result | error } across MCP and server actions
• Avoid stateful globals; set maxDuration and runtime for serverless deployments
• Use server actions to validate and mirror MCP responses for easy local testing

Example use cases

• A dice-rolling tool demonstrating a validated roll function and tool description
• Exposing database-backed tools (Prisma) for retrieval and mutations via MCP and server actions
• Testing AI tool integrations locally with a web UI that calls server actions and an MCP bridge (mcp-remote)
• Adding new tools by defining a Zod schema and function in lib/ then registering via createMcpHandler