anthropics/skills · skills/mcp-builder/SKILL.md
mcp-builder
“Anthropic's MCP server playbook: a clear route from API docs to tested tools and evals, a bit wordy”
What it does
Guides the agent through building an MCP server in TypeScript or Python. It covers research, picking an SDK version, building the tools, then testing and writing 10 read-only evaluation questions. Detailed patterns live in linked reference guides.
- When the agent uses it
- When the user wants to build an MCP server that wraps an external API or service, in Python (FastMCP) or Node/TypeScript (MCP SDK).
- Who it is for
- Install if you build MCP servers or wrap APIs for agents; skip if you only use existing servers and never write one.
- What it costs
- 176 lines, about 3k tokens once the agent loads it, plus 10 files beside it.
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
What it tells the agent to do
- Read MCP design principles and fetch the spec via its sitemap, using .md page URLs
- Pick the stack: TypeScript SDK v2 for new servers, v1 only if the project already uses it, or Python
- Study the target API and list endpoints to cover, most common first
- Build a shared API client, error helpers, formatting and pagination, then tools with schemas and annotations
- Build and test: npm run build or py_compile, the v2 self-check, then MCP Inspector
- Write 10 complex, read-only, verifiable evaluation questions in the given XML format
Lines worth reading
Straight from the file, with why each one matters.
line 3Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
A clean trigger: the task, the two stacks, and the words a request would actually use.
line 66Then continue with v1 unless the user asks to migrate.
Tells the agent to mention the upgrade once and then drop it. No surprise rewrites of your project.
line 43Then fetch specific pages with `.md` suffix for markdown format
A handy trick: the agent gets clean markdown docs instead of scraping HTML.
line 177Use READ-ONLY operations to explore available data
Evals are built without touching live data. The right guardrail for an agent poking at a real API.
line 198What number X was being determined for the model named after a spotted wild cat?
The sample eval question is a riddle about Anthropic's own model codenames. A nice in-joke.
Watch out for
- Low
npx runs unpinned packages from npm. The @latest codemod also rewrites the project in place.
line 64npx @modelcontextprotocol/codemod@latest v1-to-v2 .
- Low
The agent fetches docs from remote URLs into its context at runtime. The sources are official, but the content can change.
line 75Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
The scorecard
- TriggerSays when to use it8/10
Says what and when, names both stacks; could add words like 'tools' or 'connector'.
- FocusOne clear job8/10
One job, building MCP servers, with evals as a natural last phase.
- LeanLight to load7/10
About 250 lines with good reference files, but the doc library repeats earlier links.
- ConcreteSteps you can follow6/10
Real commands and an XML format, but much of Phases 2–3 is generic advice.
- SafeSafe to run8/10
Read-only evals, no forced migration; only unpinned npx and doc fetches.
What it does well
- Clear v1/v2 SDK rule: use v2 for new work, keep v1 when the project already has it, and mention migration once.
- Pushes heavy detail into per-language reference guides that are loaded by phase.
- The eval phase sets testable rules: read-only, stable answers that can be checked by string comparison.
How it could be better
Replace generic quality advice with checks
Lines like 'No duplicated code (DRY principle)' are things the model already knows; specific checks make review actionable.
AddReview for: - Every tool has readOnlyHint/destructiveHint set - Every list tool accepts a limit/cursor and returns a next cursor - Every error message names the failing input and a next step - Tool names share the `<service>_` prefix
Say what done looks like
The skill lists tests but never states when the server is finished.
AddDone when: the build passes, the self-check passes (v2), MCP Inspector lists every tool and each runs once, and `<evaluation>.xml` holds 10 verified qa_pairs.
Ask before running the codemod, pin versions
The codemod rewrites files in place and @latest can change under you.
AddBefore running `npx @modelcontextprotocol/codemod@<version> v1-to-v2 .`, show the command to the user and wait for approval; commit or stash changes first.
Trim the duplicate Documentation Library
The same URLs and guides appear in Phase 1 and again at the end, which costs context on every load.
Add# Reference Files - Spec: modelcontextprotocol.io sitemap (Phase 1) - Best practices: ./reference/mcp_best_practices.md - TS v2 / v1 / Python guides: ./reference/<guide>.md (Phase 2) - Evals: ./reference/evaluation.md (Phase 4)
In the skill’s folder
Listed, not read: the agent opens these only when SKILL.md sends it there.
LICENSE.txtreference/evaluation.mdreference/mcp_best_practices.mdreference/node_mcp_server.mdreference/node_mcp_server_v2.mdreference/python_mcp_server.mdscripts/connections.pyscripts/evaluation.pyscripts/example_evaluation.xmlscripts/requirements.txt
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.