MCP Builder (Anthropic, official)

tl;dr: the canonical Anthropic procedure for building an MCP server. SKILL.md is the orchestration layer; the heavy lifting is in ./reference/ (mcp_best_practices.md, node_mcp_server.md, python_mcp_server.md, evaluation.md). Recommended stack is TypeScript with the MCP SDK + Zod; Python + FastMCP + Pydantic is the supported alternative. Phase 4 — writing 10 verification questions — is what separates a hobby server from one that ships.

What it actually does

The SKILL.md we fetched on 2026-09-10 from anthropics/skills/main/skills/mcp-builder/SKILL.md defines four sequential phases. Each phase has a reference/ doc the agent is told to load via WebFetch:

Phase 1 — Deep research and planning

1. Understand modern MCP design: balance API-coverage tools vs workflow tools; clear action-oriented names (github_create_issue); concise descriptions; pagination; actionable error messages.
2. Study the MCP spec via https://modelcontextprotocol.io/sitemap.xml, then fetch pages with .md suffix.
3. Choose stack. Recommended: TypeScript with the TypeScript SDK. Streamable HTTP for remote, stdio for local. Alternative: Python with FastMCP / Python SDK.
4. Plan the API surface — list endpoints, mark the common ones first.

Phase 2 — Implementation

• Project scaffold per the language guide (./reference/node_mcp_server.md or ./reference/python_mcp_server.md).
• Shared utilities: API client + auth, error helpers, response formatting (JSON / Markdown), pagination.
• Per tool: Zod / Pydantic input schema, optional outputSchema, concise description with parameter docs, async/await, proper error handling, readOnlyHint / destructiveHint / idempotentHint / openWorldHint annotations.

Phase 3 — Review and test

• DRY, full type coverage, consistent error handling.
• TypeScript: npm run build then MCP Inspector (npx @modelcontextprotocol/inspector).
• Python: python -m py_compile your_server.py then MCP Inspector.

Phase 4 — Create evaluations

• Write 10 questions, each: independent, read-only, complex (multi-call), realistic, verifiable, stable.
• Output format is a strict XML envelope (<evaluation><qa_pair><question>…</question><answer>…</answer></qa_pair>…</evaluation>).
• Solve each question yourself before publishing — the answer is what the eval is graded against.

Install

mcp-builder ships inside Anthropic’s example-skills plugin (not the proprietary document-skills plugin):

# Claude Code — register the marketplace, then install the example-skills plugin
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Then enable mcp-builder. On Claude.ai, the example skills ship pre-built for paid plans. There is no npm package per-skill; skills.sh indexes the repo at 112.9K installs — that’s a tracking number, not a command.

What it explicitly is not

• Not a generator. It does not produce a server without the user providing the API to wrap. The skill is the workflow; the API knowledge comes from the agent’s research phase.
• Not a transport cheatsheet. It picks the transport (stdio for local, streamable HTTP for remote) but does not enumerate every MCP transport option.
• Not a registry publisher. Once the server is built, shipping it to a registry is out of scope. The skill’s deliverable is a working server + an evaluation XML file.
• sandbox_test untested — we read the package, we did not run a server build in the sandbox.

Gotchas

• The reference files must be fetched. SKILL.md says to WebFetch ./reference/node_mcp_server.md (or the python equivalent) during implementation. The skill assumes the agent can reach raw.githubusercontent.com. If the host is offline, the workflow stalls at Phase 2.
• TypeScript is recommended, not required. Python + FastMCP is a fully supported second path; the skill loads node_mcp_server.md by default, so a Python user must tell the agent to switch.
• Eval questions are the gate. Skipping Phase 4 because “the server works” is the common failure mode. The skill’s verdict is explicit: a server without evaluations is not done.
• License says “Complete terms in LICENSE.txt”. Anthropic’s example-skills plugin defaults to Apache 2.0, but the per-skill LICENSE.txt is authoritative.
• Streamable HTTP ≠ stateful sessions. The skill recommends stateless JSON over streamable HTTP for remote servers. Stateful streaming sessions are not the default — read ./reference/mcp_best_practices.md before deviating.

Related: Writing Plans (obra/superpowers) (turn an MCP spec into bite-sized tasks a junior can follow), Test-Driven Development (obra/superpowers) (the test discipline Phase 3 leans on), Systematic Debugging (obra/superpowers) (when MCP Inspector shows an unexpected tool error).