---

name: mcp-server-builder description: Use when building or extending a Model Context Protocol server that exposes tools to Claude or other agents, especially as a Next.js App Router route with mcp-handler. Covers tool design as prompt engineering, the concrete route.ts wiring, Bearer auth, and how to test tools so the model actually calls them.

MCP Server Builder

Build an MCP server whose tools a model can discover, call correctly, and recover from. This goes deeper than basic authoring: it assumes you are shipping a real HTTP server (not a local stdio toy), auth is required, and every tool call costs context or money.

When to trigger

Reach for this when you are:

• Standing up a new MCP endpoint for a product API so agents can call it directly.
• Adding a tool to an existing server and it is not getting called, or gets called with bad inputs.
• Serving MCP over streamable HTTP from a Next.js route (the mcp-handler + route.ts pattern), not stdio.
• Deciding which tools should be free and which should be metered, and how to protect the context budget.

Build sequence

Work in this order. Skipping straight to code is the most common way tools end up unusable.

1. Design the tools first. Name each tool by its action, write the description as prompt engineering, and make the input schema strict. See reference/tool-design.md.
2. Implement as a Next.js route. Use createMcpHandler with server.registerTool, wrap it in withMcpAuth + a verifyToken that resolves a Bearer key to a caller id, and return readable tool results (never throw across the transport). See reference/typescript_mcp_server.md.
3. Evaluate. Curl the endpoint (a 401 without a key proves auth), assert result shape with the MCP inspector, run a small eval harness over good and bad inputs, and iterate on descriptions when the model fails to call a tool. See reference/evaluation.md.

Core rules

• The name and description are the interface the model sees. Treat them as prompt engineering, not docs.
• Return errors as tool results with isError: true, not thrown exceptions. A thrown error kills the transport; a readable error lets the model recover.
• Validate inputs with zod at the schema boundary. Required fields required, enums for closed sets, a .describe() on every field.
• Protect the context budget. Paginate, cap limit, and summarize instead of dumping full tables.
• Charge only on success for metered tools, and say the cost in the description.

Reference files

• reference/tool-design.md - naming, descriptions, schemas, error results, pagination, free vs metered.
• reference/typescript_mcp_server.md - the concrete Next.js route.ts pattern with mcp-handler and auth.
• reference/evaluation.md - inspector, curl, result-shape asserts, an eval harness, and description iteration.