mcp-server-design

Design the surface an MCP (Model Context Protocol) server exposes to AI agents — which tools/resources/prompts exist, what they're named, what their schemas and descriptions say. This is the highest-leverage phase: most bad MCP servers fail here, not in code. The failure this skill fixes: 1:1 API-wrapped, over-tooled, under-described servers that tank agent tool-selection accuracy and burn context.

Facts below target MCP spec revision 2025-11-25 (current as of 2026-07-20).

When NOT to use

• Writing the server code with an SDK → mcp-server-implementation.
• Adding OAuth/tokens → mcp-server-auth. Threat modeling → mcp-server-security.
• Testing/evals → mcp-server-testing. Shipping/registry → mcp-server-deployment.
• Designing plain REST/GraphQL APIs for human developers — different consumer, different rules (verbose CRUD is fine there; it is the anti-pattern here).
• Choosing which existing MCP servers to install (consumer question, not design).