MCP Builder

Overview

The MCP Builder skill helps you create Model Context Protocol (MCP) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

Recommended Stack: TypeScript with streamable HTTP transport for remote servers, stdio for local servers. TypeScript offers high-quality SDK support and excellent compatibility across execution environments.

When to Use This Skill

Use the MCP Builder skill when you need to:

Build MCP servers to integrate external APIs or services
Create tools for LLMs to interact with third-party platforms
Develop workflow automation through MCP protocol
Support both Python (FastMCP) and Node/TypeScript (MCP SDK) implementations

Development Workflow

Creating a high-quality MCP server involves four main phases:

Deep Research and Planning

Understanding MCP design principles, studying protocol documentation, reviewing framework docs, and planning your implementation.

Implementation

Setting up project structure, implementing core infrastructure, and building individual tools with proper schemas and error handling.

Review and Test

Ensuring code quality, running builds, and testing with MCP Inspector to verify functionality.

Create Evaluations

Developing comprehensive test cases to verify that LLMs can effectively use your MCP server for realistic tasks.

Core Design Principles

API Coverage vs. Workflow Tools

Balance comprehensive API endpoint coverage with specialized workflow tools. While workflow tools can be more convenient for specific tasks, comprehensive coverage gives agents flexibility to compose operations.

Best Practice: Prioritize Comprehensive Coverage

When uncertain, prioritize comprehensive API coverage. Performance varies by client—some benefit from code execution that combines basic tools, while others work better with higher-level workflows.

Tool Naming and Discoverability

Clear, descriptive tool names help agents find the right tools quickly:

Use consistent prefixes (e.g., github_create_issue, github_list_repos)
Follow action-oriented naming conventions
Make tool purposes immediately obvious from the name

Context Management

Agents benefit from concise tool descriptions and the ability to filter/paginate results:

Design tools that return focused, relevant data
Support pagination for large result sets
Provide filtering options where appropriate
Some clients support code execution for efficient data processing

Actionable Error Messages

Error messages should guide agents toward solutions:

Include specific suggestions for fixing issues
Provide clear next steps
Reference documentation when relevant
Indicate required permissions or authentication

Phase 1: Deep Research and Planning

Study MCP Protocol Documentation

Start by understanding the official specification:

Navigate the sitemap: https://modelcontextprotocol.io/sitemap.xml
Fetch specific pages with .md suffix for markdown format
Review key pages:
- Specification overview and architecture
- Transport mechanisms (streamable HTTP, stdio)
- Tool, resource, and prompt definitions

Study Framework Documentation

TypeScript (Recommended)
Python

Why TypeScript?

High-quality SDK support
Good compatibility in execution environments (e.g., MCPB)
AI models excel at generating TypeScript code
Benefits from broad usage, static typing, and good linting tools

Resources:

TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Use streamable HTTP for remote servers (stateless JSON)
Use stdio for local servers

Python SDK:

Load documentation from: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
FastMCP framework provides simplified development
Good for local integrations and prototyping

Plan Your Implementation

Understand the API:

Review the service’s API documentation
Identify key endpoints and authentication requirements
Map data models and response structures

Tool Selection:

Prioritize comprehensive API coverage
List endpoints to implement, starting with most common operations
Consider workflow tools for complex multi-step operations

Phase 2: Implementation

Project Structure Setup

TypeScript
Python

// package.json example
{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "latest"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true
  }
}

# Project structure
my_mcp_server/
├── __init__.py
├── server.py
├── tools/
│   ├── __init__.py
│   └── api_tools.py
└── requirements.txt

# requirements.txt
mcp
pydantic
httpx

Core Infrastructure

Create shared utilities:

API client with authentication
Error handling helpers
Response formatting (JSON/Markdown)
Pagination support for large datasets

Implementing Tools

For each tool, follow these guidelines:

Input Schema

Use Zod (TypeScript) or Pydantic (Python) for validation:

// TypeScript with Zod
import { z } from 'zod';

const CreateIssueInput = z.object({
  title: z.string().describe('Issue title'),
  body: z.string().optional().describe('Issue description'),
  labels: z.array(z.string()).optional().describe('Labels to apply')
});

# Python with Pydantic
from pydantic import BaseModel, Field

class CreateIssueInput(BaseModel):
    title: str = Field(description="Issue title")
    body: str | None = Field(None, description="Issue description")
    labels: list[str] | None = Field(None, description="Labels to apply")

Output Schema

Define outputSchema where possible for structured data:

Use structuredContent in tool responses (TypeScript SDK feature)
Helps clients understand and process tool outputs
Enables better agent reasoning about results

Tool Implementation

Best practices:

Use async/await for I/O operations
Implement proper error handling with actionable messages
Support pagination where applicable
Return both text content and structured data when using modern SDKs

Tool Annotations:

readOnlyHint: true/false (does this tool modify data?)
destructiveHint: true/false (could this cause data loss?)
idempotentHint: true/false (safe to retry?)
openWorldHint: true/false (accesses external resources?)

Example Tool Implementation

TypeScript
Python

server.registerTool({
  name: 'github_create_issue',
  description: 'Create a new GitHub issue',
  inputSchema: zodToJsonSchema(CreateIssueInput),
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false
  },
  handler: async (args) => {
    const { title, body, labels } = args;
    
    try {
      const response = await githubClient.createIssue({
        title,
        body,
        labels
      });
      
      return {
        content: [
          {
            type: 'text',
            text: `Created issue #${response.number}: ${response.html_url}`
          }
        ]
      };
    } catch (error) {
      throw new Error(
        `Failed to create issue: ${error.message}. ` +
        `Check repository permissions and authentication.`
      );
    }
  }
});

@mcp.tool()
async def github_create_issue(
    title: str,
    body: str | None = None,
    labels: list[str] | None = None
) -> str:
    """Create a new GitHub issue.
    
    Args:
        title: Issue title
        body: Issue description
        labels: Labels to apply
    """
    try:
        response = await github_client.create_issue(
            title=title,
            body=body,
            labels=labels
        )
        return f"Created issue #{response.number}: {response.html_url}"
    except Exception as e:
        raise ValueError(
            f"Failed to create issue: {str(e)}. "
            "Check repository permissions and authentication."
        )

Phase 3: Review and Test

Code Quality Checklist

Review your implementation for:

No duplicated code (DRY principle)
Consistent error handling patterns
Full type coverage (TypeScript) or type hints (Python)
Clear, concise tool descriptions
Proper input validation
Actionable error messages

Build and Test

TypeScript
Python

# Verify compilation
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

# Verify syntax
python -m py_compile your_server.py

# Test with MCP Inspector
mcp dev your_server.py

Phase 4: Create Evaluations

After implementing your MCP server, create comprehensive evaluations to test its effectiveness.

Evaluation Purpose

Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

Creating Effective Evaluations

Tool Inspection

List available tools and understand their capabilities

Content Exploration

Use READ-ONLY operations to explore available data

Question Generation

Create 10 complex, realistic questions

Answer Verification

Solve each question yourself to verify answers

Evaluation Requirements

Ensure each question is:

Independent: Not dependent on other questions
Read-only: Only non-destructive operations required
Complex: Requiring multiple tool calls and deep exploration
Realistic: Based on real use cases humans would care about
Verifiable: Single, clear answer that can be verified by string comparison
Stable: Answer won’t change over time

Evaluation Format

<evaluation>
  <qa_pair>
    <question>
      Find discussions about AI model launches with animal codenames. 
      One model needed a specific safety designation that uses the format ASL-X. 
      What number X was being determined for the model named after a spotted wild cat?
    </question>
    <answer>3</answer>
  </qa_pair>
  <qa_pair>
    <question>Your complex question here...</question>
    <answer>Verifiable answer</answer>
  </qa_pair>
  <!-- More qa_pairs... -->
</evaluation>

Best Practices Summary

Key Takeaways:

Prioritize comprehensive API coverage over limited workflow tools
Use clear, consistent naming conventions with prefixes
Implement proper error handling with actionable messages
Define input/output schemas for all tools
Add appropriate tool annotations (readOnly, destructive, etc.)
Test thoroughly with MCP Inspector
Create realistic evaluations with verifiable answers

Transport Selection

Streamable HTTP: For remote servers (simpler to scale and maintain)
stdio: For local servers (direct process communication)

Streamable HTTP uses stateless JSON, making it easier to scale and maintain compared to stateful sessions and streaming responses.

Additional Resources

The skill includes reference files for:

MCP Best Practices: Core guidelines for server and tool design
Python Implementation Guide: Complete FastMCP patterns and examples
TypeScript Implementation Guide: Complete SDK patterns and examples
Evaluation Guide: Comprehensive evaluation creation strategies

Document Skills

Creative & Design

Development & Technical

Enterprise & Communication

Overview

When to Use This Skill

Development Workflow

Core Design Principles

API Coverage vs. Workflow Tools

Tool Naming and Discoverability

Context Management

Actionable Error Messages

Phase 1: Deep Research and Planning

Study MCP Protocol Documentation

Study Framework Documentation

Plan Your Implementation

Phase 2: Implementation

Project Structure Setup

Core Infrastructure

Implementing Tools

Example Tool Implementation

Phase 3: Review and Test

Code Quality Checklist

Build and Test

Phase 4: Create Evaluations

Evaluation Purpose

Creating Effective Evaluations

Evaluation Requirements

Evaluation Format

Best Practices Summary

Transport Selection

Additional Resources

Build docs developers (and LLMs) love

Document Skills

Creative & Design

Development & Technical

Enterprise & Communication

​Overview

​When to Use This Skill

​Development Workflow

​Core Design Principles

​API Coverage vs. Workflow Tools

​Tool Naming and Discoverability

​Context Management

​Actionable Error Messages

​Phase 1: Deep Research and Planning

​Study MCP Protocol Documentation

​Study Framework Documentation

​Plan Your Implementation

​Phase 2: Implementation

​Project Structure Setup

​Core Infrastructure

​Implementing Tools

​Example Tool Implementation

​Phase 3: Review and Test

​Code Quality Checklist

​Build and Test

​Phase 4: Create Evaluations

​Evaluation Purpose

​Creating Effective Evaluations

​Evaluation Requirements

​Evaluation Format

​Best Practices Summary

​Transport Selection

​Additional Resources

Build docs developers (and LLMs) love

Overview

When to Use This Skill

Development Workflow

Core Design Principles

API Coverage vs. Workflow Tools

Tool Naming and Discoverability

Context Management

Actionable Error Messages

Phase 1: Deep Research and Planning

Study MCP Protocol Documentation

Study Framework Documentation

Plan Your Implementation

Phase 2: Implementation

Project Structure Setup

Core Infrastructure

Implementing Tools

Example Tool Implementation

Phase 3: Review and Test

Code Quality Checklist

Build and Test

Phase 4: Create Evaluations

Evaluation Purpose

Creating Effective Evaluations

Evaluation Requirements

Evaluation Format

Best Practices Summary

Transport Selection

Additional Resources