mcp-builder

MCP Builder

An MCP server exposes tools (actions the model can call), resources (data it can read), and prompts (reusable templates) to any MCP client over a standard protocol. The whole job is: design a small set of clear, well-described tools, validate their inputs, return useful errors, and prove it works with a real client. The protocol is easy; the design of the tools is what makes the server good or useless.

Kit adaptation (local, .claude/): Stack-agnostic — TypeScript (@modelcontextprotocol/sdk) or Python (mcp / FastMCP) are the maintained SDKs; match the project's language. §4 Prohibitions apply (no AI trace in generated code/strings). Secrets (API keys the server needs) go via env, never hardcoded — the kit's secret gates apply.

Design first (the tools ARE the product)

• Few, purposeful tools — expose tasks, not a 1:1 mirror of every API endpoint. "create_invoice" beats "post_v2_billing_documents".
• The description is the interface — the model routes on it. Say what it does, when to use it, and what it returns, in plain language. A vague description = an unused or misused tool.
• Typed, validated inputs — a JSON-Schema for each tool; required vs optional explicit; enums over free strings where possible. Reject bad input with a clear message, don't guess.
• Useful returns & errors — return structured, model-readable results; on failure return an actionable error ("no invoice with id X") not a stack trace. Never crash the server on bad input.
• Least privilege — a tool does one scoped thing; destructive actions are explicit and, where possible, confirmable. Don't expose raw SQL / shell unless that is genuinely the product.

Checklist

• Tools chosen by task, not by mirroring endpoints
• Each tool has a clear description (what · when · returns) and a JSON-Schema input
• Inputs validated; bad input → clear error, not a crash
• Returns are structured and model-readable; errors are actionable
• Transport chosen (stdio for local, HTTP/SSE for remote) — see references
• Secrets via env; no hardcoded keys
• Tested against a real client (Inspector + a live client)

Protocol, SDK skeletons, transport, and testing

Concrete server skeletons (TypeScript + Python), stdio vs. HTTP transport choice, resources/prompts (not just tools), and the test loop (MCP Inspector → real client): references/building.md.

Invariant rules

1. Design the tools before writing them — task-shaped, few, clearly described.
2. Validate every input — schema-checked; bad input returns an error, never crashes.
3. Errors are for the model — actionable text it can recover from, not raw traces.
4. Secrets via env only — never hardcode credentials the server needs.
5. Prove it with a real client — a server that only "looks right" is untested.