mcp-server-skills — Claude Code skill for Next.js MCP servers
A layout for MCP servers in Next.js: shared Zod schemas, a thin route, and server actions that feed the web UI.
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a claude-codeWhat mcp-server-skills does
This skill lays out the App Router folders for an MCP server. The handler sits in app/api/[transport]/route.ts, schemas and pure logic go in lib/*, and server actions in app/actions/mcp-actions.ts import that same logic so the web UI and tests stay in step.
The point is a small route.ts. It only wires createMcpHandler from mcp-handler and registers tools with server.tool, pulling name, description and schema from the shared file. Tool replies follow one shape, { success, result | error }, which keeps MCP output and UI output from drifting apart. HTTP and SSE run through /api/[transport]; stdio needs its own entrypoint. Set basePath to match the folder path.
For desktop testing the skill shows a config that points mcp-remote at http://localhost:3000/api/mcp. Nothing connects unless that local server is up. It also warns against stateful globals, since those break on serverless hosting such as Vercel, where maxDuration and runtime may need setting.
What it helps with
- define a tool's Zod schema once and reuse it in both MCP and the UI
- keep
route.tsthin by moving logic intolib/* - check MCP tool replies through server actions in the web UI
- hook an HTTP MCP transport into Claude Desktop with
mcp-remote - standardise tool and UI responses as
{ success, result | error }
Example prompts for the agent
- Build the MCP server on Next.js with this skill: put the Zod schemas in
lib/dice.tsand wirecreateMcpHandlerinapp/api/[transport]/route.ts. - Add a
roll_dicetool plus a server action that runs the same logic for a web test. - Set up the Claude Desktop config with
mcp-remotepointing athttp://localhost:3000/api/mcp.
How to install mcp-server-skills
1Skills CLI (Vercel)
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a claude-code2Manually: put the files in place
~/.claude/skills/mcp-server-skills/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mcp-server-skills/
1Skills CLI (Vercel)
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a codex2Manually: put the files in place
.agents/skills/mcp-server-skills/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a cursor2Manually: put the files in place
.cursor/skills/mcp-server-skills/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gocallum/nextjs16-agent-skills mcp-server-skills2Manually: put the files in place
.github/skills/mcp-server-skills/SKILL.md1Skills CLI (Vercel)
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a gemini-cli2Platform CLI
gemini skills install https://github.com/gocallum/nextjs16-agent-skills --path skills/mcp-server-skillsManually: put the files in place
.devin/skills/mcp-server-skills/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mcp-server-skills
How do I install mcp-server-skills in Claude Code?
Run npx skills add gocallum/nextjs16-agent-skills --skill mcp-server-skills -a claude-code. The skill file lands at ~/.claude/skills/mcp-server-skills/SKILL.md.
What does mcp-server-skills do?
It documents a Next.js MCP server pattern: shared Zod schemas and logic in lib/*, a thin handler in app/api/[transport]/route.ts, and server actions for the web UI.
How is this different from setting up an MCP server by hand?
Schemas and logic live in one place, so MCP tools and server actions call the same code instead of duplicating it.
