Preface¶

The MCP (Model Context Protocol) has become the standard protocol for AI programming tools such as Cursor and Claude Code to connect to external APIs and services. GitHub, databases, Slack, Jira — as long as they are wrapped into an MCP Server, Agents can directly call them in conversations. However, there is often a gap between “it works” and “it is easy to use”: whether the tool names are clear, whether error messages are actionable, and whether pagination and authentication are standardized will directly affect whether the LLM can stably complete real-world tasks.

Anthropic provides a developer-facing mcp-builder Skill in its official Skills repository. It is not a ready-made MCP service, but a structured MCP server development guide — from protocol study and project scaffolding to tool registration, testing and evaluation, guiding Agents to produce maintainable server-side code in stages. This article is based on the official SKILL.md and supporting reference documents, sorting out the positioning, installation method and core workflow of this Skill.

What is this¶

mcp-builder is an Agent Skill in the skills/mcp-builder/ directory of the anthropics/skills repository, maintained by Anthropic. It follows the universal SKILL.md format and can be used in tools that support Agent Skills such as Cursor, Claude Code, and Codex CLI.

The YAML description of the Skill is as follows:

name: mcp-builder
description: 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).

In one sentence: When you need to wrap a certain external API or service into an MCP Server, enable this Skill, and the Agent will complete the design and implementation in stages according to the official best practices. The Skill itself adopts a progressive disclosure design — the main file SKILL.md gives a four-stage general process, and detailed specifications are placed in the reference/ subdirectory (such as mcp_best_practices.md, node_mcp_server.md, python_mcp_server.md, evaluation.md), which are loaded by the Agent on demand to avoid filling the context all at once.

Core Features and Highlights¶

Four-Stage Development Workflow¶

The official process is divided into four stages, covering the complete link from research to acceptance:

Phase 1 emphasizes the trade-off between “comprehensive API coverage” and “specialized workflow tools”: when in doubt, prioritize covering more endpoints to allow Agents to combine flexibly; it is recommended that tool names start with a service prefix and a verb, such as github_create_issue, slack_send_message.

Dual Language Stack Support¶

The Skill covers two officially recommended technology routes at the same time:

• TypeScript (Recommended): Use @modelcontextprotocol/sdk, cooperate with Zod for input verification, and register tools with server.registerTool(); Streamable HTTP is preferred for remote deployment, and stdio is used for local integration.
• Python: Use Python SDK / FastMCP, Pydantic to define Schema, and register tools with the @mcp.tool decorator.

Both stacks require: asynchronous I/O, actionable error messages, pagination support, and tool annotations such as readOnlyHint and destructiveHint.

Built-in Best Practice Reference Library¶

reference/mcp_best_practices.md summarizes specifications for naming, response formats, pagination, transport layer and security, for example:

• Server naming: Use {service}_mcp for Python, and {service}-mcp-server for TypeScript
• List tools default to 20–50 items per page, returning has_more and next_offset
• API keys should be stored in environment variables, hardcoding is prohibited; logs in stdio mode should be written to stderr to avoid polluting stdout

Evaluation-Driven Quality Closed Loop¶

Phase 4 requires writing 10 evaluation questions for the completed MCP Server. Each question must meet the requirements: independent, read-only, complex (multi-step tool calls), close to real scenarios, with unique and stable answers. The output is XML-formatted QA pairs, which facilitate batch script testing — this is a link emphasized by the official team but easily overlooked by many self-built MCP projects.

Installation and Activation¶

Agent Skills follow the universal directory + SKILL.md format. The installation paths vary slightly across different tools, but the general idea is consistent: place the mcp-builder folder in the Skills scan directory.

Cursor¶

Cursor will automatically discover Skills in the following locations on startup:

Operation steps:
1. Clone or download the skills/mcp-builder directory from the official repository (keep the reference/ subdirectory and all reference files).
2. Place it in the project’s .cursor/skills/mcp-builder/ or the user directory ~/.cursor/skills/mcp-builder/.
3. Restart Cursor or confirm in Settings → Rules that the Skill has been detected.
4. Describe the requirements directly in the Agent conversation (such as “Help me write an MCP Server that connects to GitHub Issues”), and the Agent will automatically match according to the description; you can also enter /mcp-builder to trigger it manually.

You can also add it via Cursor Settings → Rules → Add Rule → Remote Rule (Github), fill in https://github.com/anthropics/skills to import remotely (you need to locate the mcp-builder subdirectory yourself or install the entire repository and select it).

Claude Code¶

In Claude Code, you can install the official Anthropic Skills collection through the Plugin marketplace:

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

After installation, mention the MCP server development needs in the conversation to trigger it; if the Plugin package does not include mcp-builder, you can manually copy the directory to Claude Code’s Skills path.

Codex CLI / Other Compatible Tools¶

According to Cursor documentation, to be compatible with the Claude and Codex ecosystems, the following paths will also be scanned: .claude/skills/, .codex/skills/ and their corresponding user-level directories. Just place the mcp-builder folder in any valid path.

Typical Usage Examples¶

After enabling the Skill, put forward clear integration goals to the Agent. The following are reproducible prompts and expected behaviors sorted out based on the official guide.

Example 1: Build a TypeScript MCP Server from Scratch¶

Please use the mcp-builder skill to help me create an MCP Server that connects to the Stripe API.
Requirements: TypeScript + Streamable HTTP, implement at least two tools: list_customers and create_payment_intent.

The Agent will usually follow the Skill process:
1. Pull MCP protocol and TypeScript SDK documents;
2. Initialize the {service}-mcp-server project structure;
3. Use Zod to define inputSchema and registerTool to register tools;
4. Run npm run build, and suggest using Inspector for testing:

npx @modelcontextprotocol/inspector

Example 2: Python FastMCP Local stdio Service¶

Use the mcp-builder guide to write a Python MCP Server that exposes query interfaces for the company's internal REST API through stdio.
The tool names should be prefixed with the service, and the list interface needs pagination.

Expected implementation points (from the official Python guide):

# Tool registration example (specifically subject to SDK version)
@mcp.tool()
async def myapi_list_items(limit: int = 20, offset: int = 0) -> dict:
    """List items with pagination. Returns has_more and next_offset."""
    ...

Syntax check:

python -m py_compile your_server.py

Example 3: Write an Evaluation Set After Completion¶

The MCP Server has been implemented. Please follow the mcp-builder's evaluation guide to generate 10 read-only evaluation questions for the existing tools and output them in XML.

Example evaluation question format (extracted from the official SKILL.md):

<evaluation>
  <qa_pair>
    <question>Find the repository with the most open issues created in the last 30 days. How many issues does it have?</question>
    <answer>42</answer>
  </qa_pair>
  <!-- 10 sets of qa_pair in total -->
</evaluation>

Applicable Scenarios and Notes¶

Who is it suitable for¶

• Backend/Full-stack developers who need to wrap private or third-party REST/GraphQL APIs for use by Agents such as Cursor and Claude Code;
• Teams that already understand the basic concepts of MCP and hope to implement them according to official naming, pagination, and error handling specifications instead of copying scattered tutorials;
• Teams planning to conduct LLM availability evaluation before launching the MCP Server to reduce the situation of “the tool is registered but the Agent cannot call it correctly”.

Usage Restrictions¶

1. Skill is a guide, not a generator: It will not produce a finished Server with one click, but guide the Agent to read documents and write code in stages; the final quality still depends on the complexity of the target API and your acceptance criteria.
2. Reference files must be complete: The Markdown files under reference/ are the core dependencies for progressive loading, and only copying SKILL.md will cause the Agent to lack implementation details.
3. Security is your own responsibility: The Skill will remind about practices such as OAuth, environment variables, and input verification, but you still need to manually audit the permission scope and network exposure surface before accessing production APIs; the Anthropic official Skills repository also states that the examples are for learning and demonstration only.
4. Separate from MCP client configuration: This Skill solves “how to write a Server”; configuring the written Server into mcp.json in Cursor belongs to client integration, and you need to follow the documentation of each tool separately.

Relationship with the Agent Skills Ecosystem¶

Anthropic’s engineering blog pointed out that Agent Skills focus on teaching Agents complex workflows and domain knowledge, which can complement the external tool capabilities provided by MCP Servers — mcp-builder just stands at the intersection: using the Skill methodology to produce MCP toolchains. In December 2025, Agent Skills were released as an open standard (agentskills.io), and the porting cost across platforms such as Cursor and Claude Code is relatively low.

Conclusion¶

If you are expanding “callable external capabilities” for AI programming tools, mcp-builder is currently one of the few end-to-end development Skills maintained by Anthropic, the main promoter of the MCP protocol. It ties together protocol reading, dual-language implementation, Inspector testing, and LLM evaluation into a repeatable workflow, which is more systematic than searching for scattered tutorials.

It is recommended to obtain the complete directory from the official repository:
- Skill homepage: https://github.com/anthropics/skills/tree/main/skills/mcp-builder
- Agent Skills background: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- MCP protocol website: https://modelcontextprotocol.io

Clone skills/mcp-builder to .cursor/skills/, and next time ask the Agent “Help me write an MCP Server for XX” to experience this official workflow.