Build an MCP server whose quality is measured by one thing: can an LLM actually accomplish real tasks with it? Not endpoint coverage, not schema elegance. A server that mirrors 40 REST endpoints and leaves the model unable to complete a workflow has failed.
The most common failure is treating this as an API-wrapping exercise. Tool naming, response shape, error text, and pagination are all agent ergonomics problems, and they decide whether the server works.
Bundled from anthropics/skills commit
3b3fad96af16a10759d930941b4520ba0c40edae (2026-08-21), Apache-2.0. Upstream
ships skills/mcp-builder/LICENSE.txt; the repository root carries no SPDX
license, so the per-skill license is the operative one — see
upstream and licensing.
When to use this skill
- Wrap an external API or service as an MCP server.
- Decide tool granularity: comprehensive endpoint coverage versus workflow tools.
- Name and shape tools so an agent picks the right one unprompted.
- Choose a transport and a state model.
- Diagnose a server whose tools the model misuses or cannot chain.
- Build evaluations that prove the server enables real tasks.
Do not use this skill for neighboring jobs:
- Consume or configure an already-built MCP server: use that server's own skill.
- Design a REST or GraphQL contract for human clients: use
api-design. - Write the underlying service: this covers the MCP layer over it.
- Harden a web app generally: use
security-best-practices. - Build a non-MCP agent tool layer: use
agent-tool-routing.
Instructions
Step 0: Pick the phase
| Phase | Job | Output |
|---|---|---|
research |
understand the API and MCP design norms | tool inventory and plan |
design |
naming, granularity, response shape | tool contract |
implement |
build in TypeScript or Python | working server |
secure |
auth, validation, error handling, DNS rebinding | reviewed surface |
evaluate |
10 verified questions, harness run | pass or fail evidence |
Skipping research and design is what produces servers with 40 thin tools
that no agent can use.
Step 1: Research before writing tools
Read the target API's real semantics: resources, verbs, pagination style, auth model, rate limits, error shapes. Then decide coverage strategy.
Coverage versus workflow tools. Comprehensive endpoint coverage gives agents composition flexibility; workflow tools are more convenient for specific tasks. Performance varies by client — some benefit from code execution combining basic tools, others from higher-level workflows. Upstream's guidance when uncertain: prioritize comprehensive API coverage.
MCP specification: start at https://modelcontextprotocol.io/sitemap.xml, then
fetch pages with a .md suffix for markdown.
Step 2: Choose the stack deliberately
Upstream recommends TypeScript: strong SDK support, good compatibility in execution environments such as MCPB, static typing, and models generate it well. Python with FastMCP is fully supported and often better when the surrounding service is already Python.
| Need | Choose |
|---|---|
| Default, broad compatibility | TypeScript + MCP SDK |
| Existing Python service, scientific stack | Python + FastMCP |
Step 3: Design tools for discoverability
- Consistent prefixes:
github_create_issue,github_list_repos. - Action-oriented names: the verb says what happens.
- Concise descriptions: they are read by a model with limited context.
- Filterable, paginated results: return focused data, not everything.
- Actionable errors: an error must suggest the next step, not just report
failure.
"Invalid repo"is a dead end;"Repository not found. List available repositories with github_list_repos."is recoverable.
Full conventions in design and implementation.
Step 4: Choose transport and state model
| Transport | Use for | Note |
|---|---|---|
| stdio | local servers | simplest; process-scoped |
| Streamable HTTP | remote servers | prefer stateless JSON |
Upstream prefers stateless JSON over stateful sessions and streaming responses: simpler to scale and maintain. Choose stateful only with a concrete reason.
Step 5: Secure the surface before exposing it
- Authenticate and authorize every tool that touches private data.
- Validate all input at the boundary; never trust model-supplied arguments.
- Return errors that guide without leaking internals, stack traces, or secrets.
- Enable DNS rebinding protection on HTTP transports.
- Apply tool annotations honestly — a destructive tool marked read-only is a trap for both the agent and its user.
Step 6: Evaluate — the phase most often skipped
Ten questions, each independent, read-only, complex (multiple tool calls), realistic, verifiable by string comparison, and stable over time.
Process: inspect the tools, explore data with read-only calls, generate the questions, then solve each one yourself to verify the answer before it becomes the expected value.
<evaluation>
<qa_pair>
<question>...</question>
<answer>3</answer>
</qa_pair>
</evaluation>
Upstream ships a harness (scripts/evaluation.py, scripts/connections.py)
that runs these against a live model.
Cost and blast radius. The harness requires an Anthropic API key and spends credits per question, and it drives your server against whatever it is connected to. Confirm before running it, keep questions read-only, and point it at non-production data.
See evaluation.
Step 7: Verify what you claim
- design: every tool has a prefix, an action name, and a concise description
- implement: server starts, tools list, one call succeeds end to end
- secure: auth enforced, input validated, no secret in an error path
- evaluate: harness run with a pass count, not "evaluations were written"
State which layer you verified. Writing evaluations is not running them.
Examples
Example 1: Wrapping a REST API
Request: "Turn our internal REST API into an MCP server."
Start in research. Inventory endpoints, identify the two or three workflows
users actually perform, then decide coverage. Default to comprehensive coverage
plus a small number of workflow tools for the dominant paths.
Example 2: Agent picks the wrong tool
Request: "The model keeps calling the wrong tool."
This is design, not a bug. Check for ambiguous names, overlapping
descriptions, missing prefixes, and tools that differ only by an unstated
precondition. Rename and re-describe before touching code.
Example 3: Evaluation request with cost
Request: "Run the eval suite."
Confirm the API key source, the per-run credit cost, and that every question is read-only against non-production data. Then run and report the pass count.
Best practices
- Measure by task completion — not endpoint coverage.
- Default to comprehensive coverage — add workflow tools for real paths.
- Prefix and verb every tool name — discovery is the agent's bottleneck.
- Make errors actionable — every failure names a next step.
- Prefer stateless streamable HTTP — stateful needs a reason.
- Annotate destructive tools honestly — read-only means read-only.
- Verify eval answers yourself — an unverified expected value tests nothing.
- Gate the harness on cost and confirmation — it spends credits per run.
References
- Design and implementation
- Evaluation
- Upstream and licensing
- Capability primitives, Server Card, and registry publishing (jeo catalog addition, merged from
mcp-server-design) - MCP specification
- Upstream skill
- Audited pin
3b3fad9