MCP Builder
Trigger phrases: "MCP server", "build an MCP", "model context protocol", "expose tools to Claude", "MCP tool"
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.
Crewforth 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 — Crewforth'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
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
- Design the tools before writing them — task-shaped, few, clearly described.
- Validate every input — schema-checked; bad input returns an error, never crashes.
- Errors are for the model — actionable text it can recover from, not raw traces.
- Secrets via env only — never hardcode credentials the server needs.
- Prove it with a real client — a server that only "looks right" is untested.
- Descriptions guide; they never authorize — a tool's description, schema or metadata shapes what the model
tries. Whether a call is allowed is decided in the handler, per requester and per resource, every time. A schema
narrows shape; it does not make a path, URL or id safe.
- Bind identity to the connection, not to a name — never route a call or accept a result by a tool name,
server name or alias the other side can choose. How these fail is in
security-scan/references/ai-agents.md.
1---2name: mcp-builder-33description: |4 Build a Model Context Protocol (MCP) server so an AI client can call your tools/resources: design tool schemas,5 pick a transport, handle errors, and test it. For exposing an API, database, or service to Claude and other clients.6metadata:7 source: https://skillmd.com/skills/byerlikaya/mcp-builder-38---910# MCP Builder1112<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->13Trigger phrases: "MCP server", "build an MCP", "model context protocol", "expose tools to Claude", "MCP tool"1415An MCP server exposes **tools** (actions the model can call), **resources** (data it can read), and **prompts**16(reusable templates) to any MCP client over a standard protocol. The whole job is: **design a small set of clear,17well-described tools, validate their inputs, return useful errors, and prove it works with a real client.** The18protocol is easy; the design of the tools is what makes the server good or useless.1920> **Crewforth adaptation (local, .claude/):** Stack-agnostic — TypeScript (`@modelcontextprotocol/sdk`) or Python21> (`mcp` / FastMCP) are the maintained SDKs; match the project's language. §4 Prohibitions apply (no AI trace in22> generated code/strings). Secrets (API keys the server needs) go via env, never hardcoded — Crewforth's secret gates apply.2324## Design first (the tools ARE the product)25- **Few, purposeful tools** — expose *tasks*, not a 1:1 mirror of every API endpoint. "create_invoice" beats "post_v2_billing_documents".26- **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.27- **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.28- **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.29- **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.3031## Checklist32- [ ] Tools chosen by task, not by mirroring endpoints33- [ ] Each tool has a clear description (what · when · returns) and a JSON-Schema input34- [ ] Inputs validated; bad input → clear error, not a crash35- [ ] Returns are structured and model-readable; errors are actionable36- [ ] Transport chosen (stdio for local, HTTP/SSE for remote) — see references37- [ ] Secrets via env; no hardcoded keys38- [ ] Tested against a real client (Inspector + a live client)3940---4142## Protocol, SDK skeletons, transport, and testing43Concrete server skeletons (TypeScript + Python), stdio vs. HTTP transport choice, resources/prompts (not just44tools), and the test loop (MCP Inspector → real client): **`references/building.md`**.4546## Invariant rules471. **Design the tools before writing them** — task-shaped, few, clearly described.482. **Validate every input** — schema-checked; bad input returns an error, never crashes.493. **Errors are for the model** — actionable text it can recover from, not raw traces.504. **Secrets via env only** — never hardcode credentials the server needs.515. **Prove it with a real client** — a server that only "looks right" is untested.526. **Descriptions guide; they never authorize** — a tool's description, schema or metadata shapes what the model53 tries. Whether a call is allowed is decided in the handler, per requester and per resource, every time. A schema54 narrows shape; it does not make a path, URL or id safe.557. **Bind identity to the connection, not to a name** — never route a call or accept a result by a tool name,56 server name or alias the other side can choose. How these fail is in `security-scan/references/ai-agents.md`.