mcp-builder is Anthropic’s agent skill for creating Model Context Protocol servers that let LLMs work with external services through well-designed tools. It triggers when a user wants to integrate an API or service as an MCP server, in Python with FastMCP or in Node/TypeScript with the MCP SDK, and it walks the agent through four phases: deep research and planning, implementation, review and testing, and evaluation. Its premise is that a server’s quality is measured by how well it lets an LLM accomplish real tasks, not by how many endpoints it wraps.
The SKILL.md recommends TypeScript and Streamable HTTP with stateless JSON for remote servers (stdio for local ones), explains when to pick v2 of the TypeScript SDK (@modelcontextprotocol/server) over v1, and points the agent at bundled guides for MCP best practices, the TypeScript SDK v2 and v1, and Python with FastMCP. The last phase has the agent write ten read-only, verifiable question-and-answer pairs in XML and run them through a bundled Python harness that has Claude answer each question using only the server’s tools.
What You Get
- A four-phase SKILL.md workflow: research and planning, implementation, review and test, and evaluations, with guidance on API coverage versus workflow tools, tool naming, context management and error messages
- An MCP best practices reference covering server and tool naming, JSON and Markdown response formats, pagination, transport choice, security (OAuth, API keys, input validation, DNS rebinding protection) and tool annotations
- A TypeScript guide for SDK v2 (@modelcontextprotocol/server) with project setup, a server factory, a complete stdio and Streamable HTTP example, bearer auth, resources, prompts, a smoke-test script, a v1-to-v2 translation table and a quality checklist
- A TypeScript guide for SDK v1 (@modelcontextprotocol/sdk) for projects that already depend on it
- A Python guide for FastMCP with Pydantic v2 input models, response formats, pagination, error handling, context injection, resources, lifespan management and a quality checklist
- An evaluation guide and harness: evaluation.py and connections.py connect to a server over stdio, SSE or Streamable HTTP and run each XML question through a Claude tool-use loop, with an example evaluation file and a requirements file
Common Use Cases
- Wrapping a SaaS or internal REST API as an MCP server so Claude and other agents can search, read and act on it
- Starting a new TypeScript MCP server on SDK v2 with both stdio and Streamable HTTP transports
- Building a Python MCP server with FastMCP and Pydantic-validated tools
- Migrating an existing v1 TypeScript MCP server to SDK v2 with the official codemod
- Measuring whether an LLM can actually answer realistic questions with a server’s tools, and using the agent’s feedback to improve tool names, descriptions and outputs
What Makes It Unique
The other Anthropic skills listed here either shape output, like frontend-design and pdf, or teach the platform, like claude-api, which covers calling Claude from code. mcp-builder is about the opposite direction: designing tools that an LLM will call. Its advice is aimed at the model as the user of the server (service-prefixed tool names, concise descriptions, paginated and size-capped responses, errors that say how to recover), and it closes with a measurement loop rather than a checklist alone: ten stable, string-verifiable questions run through Claude against the live server, with Claude’s feedback on each tool in the report.
Under The Hood
SKILL.md is a phased guide that sends the agent to its reference files as needed: mcp_best_practices.md first, then the TypeScript v2, TypeScript v1 or Python guide for the chosen stack, and evaluation.md for the last phase. It tells the agent to fetch the MCP specification starting from the modelcontextprotocol.io sitemap and the Python and TypeScript SDK READMEs from raw.githubusercontent.com, and to use web search for the target service’s API documentation. The agent writes the server’s files in the user’s project and runs commands such as npm run build, python -m py_compile, npx @modelcontextprotocol/inspector and, for v1 projects being migrated, npx @modelcontextprotocol/codemod@latest. For the evaluation phase the agent installs the anthropic and mcp Python packages from requirements.txt and runs scripts/evaluation.py with an ANTHROPIC_API_KEY from the environment. The script reads the XML question file, connects to the server through connections.py (launching it as a subprocess for stdio, or connecting to a running server’s URL with optional headers for SSE and HTTP), sends each question to the Anthropic Messages API with the server’s tools, executes the tool calls Claude makes against the server, and prints or writes a Markdown report with accuracy, durations, tool-call counts and Claude’s feedback on the tools. Those API calls cost money.