The mcp-builder skill: build MCP servers with Claude

Source: anthropics/skills · Maintainer: Anthropic · License: Apache 2.0 · Checked: 23 October 2026

What is the mcp-builder skill?

The mcp-builder skill is Anthropic's playbook for having an agent build a Model Context Protocol (MCP) server: a small program that exposes an API or service as tools a model can call. It is for developers who want Claude Code, Codex or another agent to produce a server that is well designed for models, not just one that compiles.

Its official description in the SKILL.md reads: "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)."

The skill sits in the anthropics/skills repo (about 183,000 stars when checked). Its skills.sh page showed 130.7K installs on 23 October 2026. If you are new to MCP, read skills vs MCP first; the short version is that a skill teaches the agent how to do something, while an MCP server gives it new tools.

What does the mcp-builder skill do?

The agent loads it when you ask to build an MCP server or wrap an API for a model. The SKILL.md then walks through four phases.

1. Research and planning. Study MCP design: balance full API coverage against higher-level workflow tools (when unsure, it says to favor coverage), name tools clearly with a shared prefix such as github_create_issue, keep responses focused, and write error messages that tell the agent what to do next. It points the agent at the MCP spec on modelcontextprotocol.io and at the official TypeScript and Python SDK READMEs.
2. Implementation. Set up the project, build shared pieces (an authenticated API client, error helpers, JSON or Markdown response formatting, pagination), then write each tool with an input schema (Zod for TypeScript, Pydantic for Python), an output schema where possible, and annotations: readOnlyHint, destructiveHint, idempotentHint and openWorldHint.
3. Review and test. Check for duplicated code, consistent errors and full types. For TypeScript, run npm run build; for Python, check syntax with python -m py_compile. Test either one with the MCP Inspector.
4. Evaluations. Write 10 realistic questions that each need several tool calls, are read-only, have one verifiable answer and won't change over time, and save them as XML.

The recommended stack is TypeScript, with streamable HTTP for remote servers (stateless JSON) and stdio for local ones. The bundled best-practices file adds conventions: name Python servers {service}_mcp and Node servers {service}-mcp-server, use snake_case tool names with a service prefix, default to 20 to 50 items per page, and avoid SSE, which it calls deprecated in favor of streamable HTTP.

What is in the folder?

• SKILL.md: the four-phase workflow and an index of the references.
• reference/mcp_best_practices.md: naming, response formats, pagination, transports, security and errors.
• reference/node_mcp_server.md: the TypeScript guide, with project structure, Zod schemas and server.registerTool examples.
• reference/python_mcp_server.md: the Python guide, with FastMCP, Pydantic models and @mcp.tool examples.
• reference/evaluation.md: how to write evaluation questions and run the harness.
• scripts/evaluation.py and scripts/connections.py: an evaluation harness that connects to your server over stdio, SSE or HTTP and has Claude answer each question.
• scripts/example_evaluation.xml and scripts/requirements.txt.
• LICENSE.txt: Apache 2.0.

How do you install the mcp-builder skill?

Claude Code plugin. The anthropics/skills README documents these commands for a Claude Code session:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

That installs Anthropic's whole example-skills plugin, which includes mcp-builder alongside skills such as skill-creator and webapp-testing.

The skills CLI. To install just this skill, use the command from its skills.sh page:

npx skills add https://github.com/anthropics/skills --skill mcp-builder

Per the skills CLI reference, add -g to install for all projects and -a claude-code to target Claude Code. The folder then lands in .claude/skills/mcp-builder/ in your project, or ~/.claude/skills/mcp-builder/ globally. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

Claude.ai. The README says the example skills "are all already available to paid plans in Claude.ai." You turn them on under Customize, Skills, as Anthropic's article on using skills in Claude describes.

How do you use it?

Describe the server you want and the service behind it. Some prompts that fit:

• "Build an MCP server in TypeScript for our internal tickets API. Start with list, search and get tools, all read-only."
• "Wrap the Notion API as a Python MCP server using FastMCP, with pagination on every list tool."
• "Review my MCP server against the mcp-builder best practices and fix tool names, descriptions and annotations."
• "Write 10 evaluation questions for this server and save them as evaluation.xml."
• "Convert this stdio server so it can also run over streamable HTTP."

When the server works, add it to your agent; Claude Code MCP covers the claude mcp add side.

Requirements

Building the server needs whatever the chosen stack needs: Node and npm for TypeScript, Python for FastMCP. The optional evaluation harness has its own setup, from reference/evaluation.md:

pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key_here

requirements.txt pins anthropic>=0.39.0 and mcp>=1.1.0. A run against a local stdio server looks like this (the script starts the server itself):

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml

Tips and limits

• Set the model for evaluations. The harness defaults to claude-3-7-sonnet-20250219, which Anthropic's model deprecations page lists as retired on 19 February 2026. Pass a current model ID with -m; that page names claude-sonnet-5-5 as the replacement.
• Evaluations cost money. Each run sends every question through the Anthropic API with your key. Keep the question set small while iterating.
• Keep evaluation questions read-only. The guide insists on non-destructive questions, because the harness really calls your server's tools against real data.
• Remote transports need a running server. With -t sse or -t http, start the server yourself first; only stdio is launched by the script.
• It fetches docs from the web. Phase 1 tells the agent to load the MCP spec and SDK READMEs over the network. In an offline or locked-down setup, give it those docs another way.
• Security is on you. The skill covers auth and error handling in its best-practices file, but an MCP server can read and write real systems. Review the tools, especially anything with destructiveHint: true, before connecting it to production accounts.
• Demonstration status. Anthropic's README says these skills are "provided for demonstration and educational purposes only." skills.sh also lists third-party security audit results for the skill.

Save it in your Kipt library

Kipt keeps the skills you rely on in one private library. Open Skills in Kipt and paste the skill's GitHub folder link into the import box; Kipt reads the SKILL.md and its files, and for a repo with many skills it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Similar skills

• skill-creator: Anthropic's skill for writing and testing your own skills.
• webapp-testing skill: test a web app that uses your new server.
• Best MCP servers: servers worth installing before you build your own.
• find-skills skill: check whether a skill already covers the job.