mcp-builderlisted

# MCP Server Development Guide ## Why this skill exists Wrapping an external API in an MCP server sounds simple, but naive implementations fail in practice: tools return walls of JSON that exhaust context, list operations return unbounded results that time out, error messages say "400 Bad Request" without guidance, and tool names are so generic (`get`, `list`) that the model picks wrong ones. This guide enforces the patterns — pagination-first, structured output, actionable errors, consistent naming — that make the difference between a server a model can use reliably and one it struggles with. **MCP is a protocol, not a Claude feature.** The server you build here is host-neutral: the same stdio or HTTP server is consumed by Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, OpenCode and anything else speaking MCP. Nothing in the server implementation may assume a particular host. What *does* differ per host is the **client config file** that registers the server — that difference is confined to Phase 6, where it is generated and validated per target, and it never leaks into the server code. Throughout this guide, "the client" or "the host" means whichever agent runtime is calling your tools. Where a passage says Claude, it is naming one client among several, not a requirement. ## Supporting files | File | When to use | |------|-------------| | `scripts/scaffold.sh` | Run at the start of Phase 2 to generate a project skeleton. Usage: `bash <skill-dir>/scripts/sc