mcp-builder

Overview

What mcp-builder is

mcp-builder is a development-focused skill for teams building MCP (Model Context Protocol) servers. It is designed to help developers create servers that let models use external services through well-structured tools, with practical guidance on architecture, naming, transport, implementation patterns, and evaluation.

Rather than acting as a runnable server itself, mcp-builder works as a reference-driven build guide. In this skill, the core materials are SKILL.md plus supporting documents in reference/ and helper scripts in scripts/.

Who should use mcp-builder

This skill is a strong fit for:

• Developers creating a new mcp-server for an API, SaaS platform, internal system, or workflow
• Teams deciding between Python FastMCP and Node/TypeScript MCP SDK implementations
• Builders who need better mcp-tools naming, schema design, and response patterns for Claude or other Anthropic-compatible workflows
• Engineers who want a repeatable way to evaluate server quality with realistic, tool-based questions

What problems this skill helps solve

mcp-builder focuses on the parts of MCP server development that most affect real-world usability:

• Choosing between broad API coverage and higher-level workflow tools
• Naming servers and tools so agents can discover them more reliably
• Designing outputs that work for both structured processing and readable responses
• Selecting the right transport, including stdio or streamable HTTP
• Implementing servers in Python or Node/TypeScript using supported MCP SDK patterns
• Testing whether an agent can actually complete complex tasks with the tools provided

What is included in the repository

The published repository evidence supports a documentation-first structure with implementation references and evaluation helpers:

• SKILL.md for the main MCP server development workflow
• reference/mcp_best_practices.md for naming, pagination, response format, and transport guidance
• reference/python_mcp_server.md for Python FastMCP patterns
• reference/node_mcp_server.md for Node/TypeScript MCP SDK patterns
• reference/evaluation.md for evaluation design rules
• scripts/evaluation.py and scripts/connections.py for running an evaluation harness against MCP servers
• scripts/example_evaluation.xml and scripts/requirements.txt for evaluation support files

Why mcp-builder stands out

The value of mcp-builder is that it treats server quality as more than just exposing endpoints. The source material explicitly frames success around whether an LLM can use the MCP server to answer realistic tasks well. That makes this skill especially useful if you care about actual agent performance, not only technical completeness.

When mcp-builder is a good fit

Use mcp-builder when you are:

• Planning a new MCP integration from scratch
• Refactoring an existing server with unclear tool names or weak schemas
• Comparing Python and TypeScript implementation approaches
• Building an internal quality checklist before publishing an MCP server
• Creating evaluation questions to verify that the server supports realistic workflows

When mcp-builder may not be the best fit

This skill may be less useful if you need:

• A drop-in MCP server package for a specific service with no custom development work
• A general non-MCP API tutorial
• A hosted product or GUI-based setup experience

It is best understood as a builder's guide and evaluation aid, not a finished end-user integration.

How to Use

Install mcp-builder

Add the skill from the anthropics/skills repository:

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

After installation, open the local skill files and read them in this order for the fastest onboarding.

Start with the main workflow

Begin with SKILL.md. This is the main guide for the skill and introduces the development process for creating high-quality MCP servers.

The repository evidence shows that the workflow starts with research and planning, including modern MCP design choices such as:

• balancing comprehensive endpoint coverage with specialized workflow tools
• using clear, descriptive tool names
• keeping context manageable with concise descriptions and filtering or pagination support

Use the best-practices reference before coding

Open reference/mcp_best_practices.md next. This file is the quickest way to understand the opinionated conventions used by mcp-builder.

Key supported topics include:

• server naming conventions for Python and Node/TypeScript
• tool naming with service-prefixed snake_case
• response format guidance for JSON and Markdown
• pagination expectations such as limit, has_more, next_offset, and total_count
• transport recommendations, including streamable HTTP for remote use and stdio for local integrations

This reference is especially useful if you are deciding how your MCP server should look before implementation begins.

Choose your implementation path

Python path with FastMCP

If you are building in Python, review reference/python_mcp_server.md.

The repository evidence shows this guide covers:

• use of FastMCP from the MCP Python SDK
• decorator-based tool registration with @mcp.tool
• Pydantic-based input validation patterns
• server naming with the {service}_mcp convention

mcp-builder is a good fit for Python teams that want a higher-level framework and straightforward tool registration patterns.

Node/TypeScript path with the MCP SDK

If you are building in Node or TypeScript, review reference/node_mcp_server.md.

The repository evidence shows this guide covers:

• McpServer setup from @modelcontextprotocol/sdk
• registerTool usage
• Zod-based input validation
• StreamableHTTPServerTransport and StdioServerTransport
• structured output patterns using structuredContent

This path is a good match for teams already shipping TypeScript services or wanting strong schema ergonomics with Zod.

Use the evaluation guide to test real usability

One of the most useful parts of mcp-builder is its evaluation emphasis. Read reference/evaluation.md when your server is functional enough to test.

According to the repository source, the evaluation guidance recommends creating 10 human-readable questions that are:

• read-only
• independent
• non-destructive
• answerable with a single verifiable value
• complex enough to require multiple tool calls

That makes the skill especially relevant for skill-testing as a secondary use case. It helps you validate whether an LLM can actually use your server effectively, rather than only checking whether tool handlers run.

Review the helper scripts

The scripts/ folder provides evaluation-related support.

Based on the repository evidence:

• scripts/connections.py contains lightweight connection handling for MCP servers and supports multiple connection types, including stdio, SSE-related client code, and streamable HTTP client code
• scripts/evaluation.py is an MCP server evaluation harness that runs test questions using Claude through the Anthropic API
• scripts/example_evaluation.xml provides an example XML structure for question-and-answer pairs
• scripts/requirements.txt lists Python dependencies for the evaluation tooling

If your goal is to benchmark an MCP server with Claude in a practical workflow, these files are worth reviewing closely.

Suggested adoption workflow

A practical way to use mcp-builder in a new project is:

1. Install the skill.
2. Read SKILL.md for the overall workflow.
3. Review reference/mcp_best_practices.md to lock down naming, transport, and response decisions.
4. Choose either reference/python_mcp_server.md or reference/node_mcp_server.md based on your stack.
5. Build your first tool set with clear names and schemas.
6. Create realistic evaluation questions using reference/evaluation.md.
7. Inspect scripts/evaluation.py and related files if you want an automated evaluation harness.

Installation decision notes

mcp-builder is easiest to recommend when your team needs guidance and standards, not just code snippets. It is particularly valuable if you are still answering questions like:

• Should we expose raw API operations, workflow tools, or both?
• How should our tools be named so Claude can find them naturally?
• Which transport should we use for local versus remote deployment?
• How do we prove the server works well in realistic agent tasks?

If those are your current blockers, this skill is likely worth installing.

FAQ

Is mcp-builder an MCP server I can run directly?

No. Based on the repository structure and documentation, mcp-builder is a guide-oriented skill for building MCP servers. It includes references and evaluation helpers, but it is not presented as a ready-made server for a specific service.

How do I install mcp-builder?

Use:

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

Then read SKILL.md and the reference/ documents locally.

Does mcp-builder support Python and Node?

Yes. The repository includes separate references for both:

• reference/python_mcp_server.md
• reference/node_mcp_server.md

The Python guide uses FastMCP patterns, while the Node/TypeScript guide uses the MCP TypeScript SDK.

Does mcp-builder help with MCP server testing?

Yes. This is one of its strongest practical benefits. reference/evaluation.md explains how to design realistic evaluation questions, and scripts/evaluation.py provides an evaluation harness that uses Claude via the Anthropic API.

What transport guidance does mcp-builder include?

The best-practices reference recommends streamable HTTP for remote and multi-client scenarios, and stdio for local integrations and command-line use. It also notes avoiding SSE in favor of streamable HTTP in the best-practices documentation.

What naming conventions does mcp-builder recommend?

The repository guidance recommends:

• Python server names like {service}_mcp
• Node/TypeScript server names like {service}-mcp-server
• service-prefixed tool names in snake_case, such as github_create_issue

These conventions improve discoverability when multiple MCP tools are available.

Is mcp-builder a good fit for production teams?

Yes, especially for teams that want a more disciplined MCP development workflow. It is useful for production planning because it covers implementation patterns, transport choices, naming consistency, and evaluation criteria. That said, you still need to build and maintain your own actual server implementation.

When should I skip mcp-builder?

Skip it if you already have a mature MCP server architecture and only need a narrow code example, or if you are not building MCP tooling at all. mcp-builder is most valuable during design, implementation, and evaluation of new or improving MCP servers.