MCP Server Builder

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

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.

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

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

1. Measure by task completion — not endpoint coverage.
2. Default to comprehensive coverage — add workflow tools for real paths.
3. Prefix and verb every tool name — discovery is the agent's bottleneck.
4. Make errors actionable — every failure names a next step.
5. Prefer stateless streamable HTTP — stateful needs a reason.
6. Annotate destructive tools honestly — read-only means read-only.
7. Verify eval answers yourself — an unverified expected value tests nothing.
8. 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